home *** CD-ROM | disk | FTP | other *** search
/ Amiga Format CD 41 / Amiga Format CD41 (1999-06)(Future Publishing)(GB)[!][issue 1999-07].iso / -seriously_amiga- / programming / other / gtlayout / autodocs / gtlayout.doc
Text File  |  1999-04-19  |  133KB  |  3,920 lines
  1. TABLE OF CONTENTS
  2.  
  3. gtlayout.library/--background--
  4. gtlayout.library/--version--
  5. gtlayout.library/LT_Activate
  6. gtlayout.library/LT_BeginRefresh
  7. gtlayout.library/LT_BuildA
  8. gtlayout.library/LT_CatchUpRefresh
  9. gtlayout.library/LT_CreateHandleTagList
  10. gtlayout.library/LT_DeleteHandle
  11. gtlayout.library/LT_DeleteWindowLock
  12. gtlayout.library/LT_DisposeMenu
  13. gtlayout.library/LT_EndGroup
  14. gtlayout.library/LT_EndRefresh
  15. gtlayout.library/LT_Exit
  16. gtlayout.library/LT_FindMenuCommand
  17. gtlayout.library/LT_GetAttributesA
  18. gtlayout.library/LT_GetCode
  19. gtlayout.library/LT_GetIMsg
  20. gtlayout.library/LT_GetMenuItem
  21. gtlayout.library/LT_GetWindowUserData
  22. gtlayout.library/LT_HandleInput
  23. gtlayout.library/LT_Init
  24. gtlayout.library/LT_LabelChars
  25. gtlayout.library/LT_LabelWidth
  26. gtlayout.library/LT_LayoutMenusA
  27. gtlayout.library/LT_LevelWidth
  28. gtlayout.library/LT_LockWindow
  29. gtlayout.library/LT_MenuControlTagList
  30. gtlayout.library/LT_NewA
  31. gtlayout.library/LT_NewLevelWidth
  32. gtlayout.library/LT_NewMenuTagList
  33. gtlayout.library/LT_NewMenuTemplate
  34. gtlayout.library/LT_PressButton
  35. gtlayout.library/LT_RebuildTagList
  36. gtlayout.library/LT_Refresh
  37. gtlayout.library/LT_ReplyIMsg
  38. gtlayout.library/LT_SetAttributesA
  39. gtlayout.library/LT_ShowWindow
  40. gtlayout.library/LT_UnlockWindow
  41. gtlayout.library/LT_UpdateStrings
  42. gtlayout.library/--background--               gtlayout.library/--background--
  43.  
  44.    NOTES
  45.     1. General information
  46.  
  47.     1.1 Purpose
  48.  
  49.     The GUI code included in this archive helps to create user interfaces
  50.     using gadtools.library with a minimum of effort. The code
  51.     automatically takes care of the font to be used, making the user
  52.     interface font independent. Localizing support is built right into
  53.     the code, just install a callback hook and pass numeric IDs for the
  54.     gadget labels: the code will invoke your hook in order to get the
  55.     text required. Keystroke activation of gadgets is also taken care
  56.     of, in fact the code will -- unless told not to do so -- assign keyboard
  57.     shortcuts to the gadgets created all on its own. Every effort has been
  58.     made to make the code reentrant, so it can be put into a shared library.
  59.     If a user interface does not fit onto a screen provisions are made to
  60.     choose a smaller font and to rescale the window contents until they fit.
  61.     Last but not least the user interface code offers transparent extensions
  62.     to the standard gadtools.library objects, such as LISTVIEW_KIND objects
  63.     which respond to double-clicks or STRING_KIND objects which can be used
  64.     to enter password text as they will not display the characters entered.
  65.  
  66.  
  67.     1.2 Distribution
  68.  
  69.     The code is *free*, you don't need to pay any money to use it, nor
  70.     do you need to quote my name in the documentation, the program or
  71.     anywhere else. You are allowed to make changes to the code, but if
  72.     you stumble across any bugs or even know how to fix them, please
  73.     let me know. It does not matter whether you intend to sell a program
  74.     to use the code, use the code in shareware, gift-ware, freeware or
  75.     etc.-ware programs: the code still remains royalty-free.
  76.  
  77.  
  78.     1.3 Caveats
  79.  
  80.     The code is pretty large, about 80K-100K bytes in size. Not all
  81.     gadtools.library type objects are supported, notably
  82.     GENERIC_KIND objects. The code is not as flexible as
  83.     gadtools.library, so certain things which are easily done using
  84.     gadtools.library may be pretty difficult or even impossible.
  85.     The code is written entirely in `C' and requires SAS/C to
  86.     compile. Some parts of the code are highly recursive; I haven't
  87.     tested how much stack they might require in certain cases,
  88.     but I recommend that you don't overuse the grouping feature.
  89.     The data structures required to create and maintain the
  90.     user interface are huge, a single window might require more
  91.     than 4K-6K of memory. Proportional font support only works
  92.     well starting with Kickstart v39 and up, v2.04 will probably
  93.     not look quite that pretty.
  94.  
  95.  
  96.     2. Programming
  97.  
  98.     2.1 Client libraries required for link library version
  99.  
  100.     You need to have SysBase and GadToolsBase initialized in order to make
  101.     use of the code, i.e. your code has to do
  102.     WaitPort()...GT_GetIMsg()...GT_ReplyIMsg all on its own. The code makes
  103.     use of the memory pools introduced in exec.library v39, but calls the
  104.     equivalent routines in amiga.lib. Note: as of this writing the pools
  105.     code in amiga.lib v40.14 is broken, so you need to link with Mike
  106.     Sinz' fixed pools.lib.
  107.  
  108.  
  109.     2.2 Invocation procedure
  110.  
  111.     The typical invocation procedure looks roughly like this:
  112.  
  113.        LT_Init();    // only for link library version
  114.        :
  115.        :
  116.           LT_CreateHandleTags();
  117.              LT_New();
  118.              :
  119.              :
  120.              LT_New();
  121.                 LT_Build();
  122.                    LT_HandleInput();
  123.           LT_DeleteHandle();
  124.        :
  125.        :
  126.        LT_Exit();    // only for link library version
  127.  
  128.     You need to call LT_Init() only once in your program, it will initialize
  129.     the libraries and global data structures required by the user interface
  130.     code. When you are finished with the user interface and your program is
  131.     about to exit you need to call LT_Exit() or memory will get lost.
  132.     Note that LT_Init() is not protected against multiple invocations. If
  133.     called repeatedly memory will get lost which can never be reclaimed.
  134.     However, LT_Exit() is protected against multiple invocations, you can
  135.     also call it before ever giving LT_Init() a call, but I doubt this
  136.     would make much sense. If you are using the shared gtlayout.library
  137.     no call to LT_Init()/LT_Exit() is necessary as these calls are already
  138.     wrapped into the library opening code.
  139.        Before you can actually start building a window layout a call to
  140.     LT_CreateHandleTags() needs to be made. You need to pass in a pointer
  141.     to the Screen your user interface window is to be opened on and,
  142.     optionally, a few tags to control the look and performance of the
  143.     interface. *Never* close the screen in question before calling
  144.     LT_DeleteHandle() or nasty things will happen. For public screens
  145.     the code will try to lock the screen in question. With the handle
  146.     LT_CreateHandleTags() returned you can call LT_New() to build the
  147.     user interface. When finished a call to LT_Build() will finally
  148.     open a window and place the gadgets inside. A pointer to the
  149.     Window created will be returned, ready to be used for the
  150.     WaitPort()...GT_GetIMsg()...LT_HandleInput()...GT_ReplyIMsg()
  151.     loop. When finished, a call to LT_DeleteHandle() will close the
  152.     window and release all the memory associated with it. The design
  153.     of the interface code is similar to the corresponding calls in
  154.     gadtools.library, i.e. you don't need to worry about LT_New()
  155.     failing to allocate memory for the objects required. When it comes
  156.     to LT_Build() the code will know about any trouble which would
  157.     show up during previous invocations of LT_New(). In essence,
  158.     if LT_Build() returns NULL something is wrong.
  159.  
  160.  
  161.     2.3 Hierarchic grouping
  162.  
  163.     The basic building block of the user interface is a group, either
  164.     a horizontal or a vertical group. Adding gadgets or other objects
  165.     to a horizontal group will place them side by side from left to
  166.     right. A vertical group causes objects to be place from top to
  167.     bottom in one straight line. Groups help to arrange objects
  168.     neatly stacked, centered and properly aligned with other
  169.     members of the group.
  170.  
  171.     MUCHO IMPORTANTE: there is a bug lurking in the code which I never
  172.     had the luck to find and fix. One would expect to create
  173.     user interface structures like this:
  174.  
  175.        <group start>
  176.           <button>
  177.           <list>
  178.           <group start>
  179.              <slider>
  180.              <text>
  181.           <group end>
  182.           <button>
  183.        <group end>
  184.  
  185.     However, it is in fact not possible to mix gadgets and groups.
  186.     Thus, the user interface structure would have to look like this:
  187.  
  188.        <group start>
  189.           <group start>
  190.              <button>
  191.              <list>
  192.           <group end>
  193.           <group start>
  194.              <slider>
  195.              <text>
  196.           <group end>
  197.           <group start>
  198.              <button>
  199.           <group end>
  200.        <group end>
  201.  
  202.     Or in other words: groups only mix with other groups.
  203.  
  204.     You build groups using three different object types. In this
  205.     context `object type' refers to a specific numeric value the
  206.     LT_New() routine knows which will cause it to add another leaf
  207.     to the user interface structure tree. Here is an example:
  208.  
  209.        struct LayoutHandle *Handle;
  210.  
  211.        if(Handle = LT_CreateHandleTags(NULL,
  212.           LAHN_AutoActivate,FALSE,
  213.        TAG_DONE))
  214.        {
  215.           struct Window *Window;
  216.  
  217.           LT_New(Handle,
  218.              LA_Type,      VERTICAL_KIND,  /* A vertical group. */
  219.              LA_LabelText, "Main group",   /* Group title text. */
  220.           TAG_DONE);
  221.           {
  222.              LT_New(Handle,
  223.                 LA_Type,      BUTTON_KIND, /* A plain button. */
  224.                 LA_LabelText, "A button",
  225.                 LA_ID,        11,
  226.              TAG_DONE);
  227.  
  228.              LT_New(Handle,
  229.                 LA_Type,      XBAR_KIND,   /* A separator bar. */
  230.              TAG_DONE);
  231.  
  232.              LT_New(Handle,
  233.                 LA_Type,      BUTTON_KIND, /* A plain button. */
  234.                 LA_LabelText, "Another button",
  235.                 LA_ID,        22,
  236.              TAG_DONE);
  237.  
  238.              LT_New(Handle,
  239.                 LA_Type,      END_KIND,    /* This ends the current group. */
  240.              TAG_DONE);
  241.           }
  242.  
  243.           if(Window = LT_Build(Handle,
  244.             LAWN_Title,     "Window title",
  245.             LAWN_IDCMP,     IDCMP_CLOSEWINDOW,
  246.             WA_CloseGadget, TRUE,
  247.           TAG_DONE))
  248.           {
  249.               struct IntuiMessage *Message;
  250.               ULONG                MsgQualifier,
  251.                                    MsgClass;
  252.               UWORD                MsgCode;
  253.               struct Gadget       *MsgGadget;
  254.               BOOL                 Done = FALSE;
  255.  
  256.               do
  257.               {
  258.                   WaitPort(Window->UserPort);
  259.  
  260.                   while(Message = GT_GetIMsg(Window->UserPort))
  261.                   {
  262.                      MsgClass     = Message->Class;
  263.                      MsgCode      = Message->Code;
  264.                      MsgQualifier = Message->Qualifier;
  265.                      MsgGadget    = Message->IAddress;
  266.  
  267.                      GT_ReplyIMsg(Message);
  268.  
  269.                      LT_HandleInput(Handle,MsgQualifier,&MsgClass,
  270.                          &MsgCode,&MsgGadget);
  271.  
  272.                      switch(MsgClass)
  273.                      {
  274.                         case IDCMP_CLOSEWINDOW:
  275.  
  276.                             Done = TRUE;
  277.                             break;
  278.  
  279.                         case IDCMP_GADGETUP:
  280.  
  281.                             switch(MsgGadget->GadgetID)
  282.                             {
  283.                                 case 11: printf("First gadget\n");
  284.                                          break;
  285.  
  286.                                 case 22: printf("Second gadget\n");
  287.                                          break;
  288.                             }
  289.  
  290.                             break;
  291.                      }
  292.                   }
  293.               }
  294.               while(!Done);
  295.           }
  296.  
  297.           LT_DeleteHandle(Handle);
  298.        }
  299.  
  300.     The example creates one single group, places a few objects inside,
  301.     calls the layout routine, handles the input and finally cleans
  302.     things up again. This example also shows that you *need* at
  303.     least one group in your tree (to form the root) in order to get
  304.     things to work.
  305.        The input loop requires you to call LT_HandleInput() in order
  306.     to get the user interface code to filter out certain events and
  307.     to update internal information. The data passed in must have
  308.     been processed via the gadtools.library routines. You *must not*
  309.     call LT_HandleInput() before GT_ReplyIMsg() is called since the
  310.     routine may call intuition.library and gadtools.library routines
  311.     which in turn might lead to a system lock-up if the message
  312.     has not been processed yet. The first thing to do after LT_HandleInput()
  313.     has done whatever was necessary to the data you passed in is
  314.     examine the MsgClass variable. The user interface code will
  315.     `fake' certain message events using the variables passed in,
  316.     *do not* use any other data gathered from the original
  317.     IntuiMessage. The MsgClass may include event types you did
  318.     not ask for, i.e. the IDCMP flags of the window opened
  319.     will be set according to the objects you added to the window.
  320.     Also, the IDCMP_IDCMPUPDATE message class will show up for
  321.     certain objects. More on this later in this document.
  322.  
  323.  
  324.     2.4 Setting and getting object attributes
  325.  
  326.     The mechanism to update and query object attributes does not
  327.     exactly match the familiar gadtools.library interface. In
  328.     fact, the routine to change gadget attributes will forward
  329.     the tagitem list passed in to gadtools.library/GT_SetGadgetAttrs().
  330.     On the other hand the routine to query object attributes does
  331.     not work like gadtools.library/GT_GetGadgetAttrs(). The
  332.     user interface code assumes that all objects it can handle and
  333.     create posess certain attributes unique to the type of the
  334.     object in question. For example, the unique attribute of a
  335.     STRING_KIND object would be a pointer to the string it
  336.     `contains'. The unique attribute of a SLIDER_KIND object is
  337.     the current slider position. The LT_GetAttributes() routine
  338.     will return this attribute, but also accept a tagitem list
  339.     to fill in for certain special tag values.
  340.  
  341.  
  342.     2.5 Extra data
  343.  
  344.     Once a LayoutHandle has been created the interface code will
  345.     provide you with a number of information concerning the screen
  346.     the handle has been attached to. This information includes
  347.     the DrawInfo structure of the screen, the VisualInfo data
  348.     and the Screen address. This information is read-only.
  349.  
  350.  
  351.     2.6 Menus
  352.  
  353.     With a LayoutHandle available a routine called LT_LayoutMenuTags()
  354.     will create a standard Intuition menu structure via gadtools.library
  355.     which can be passed to LT_Build(). Note that this
  356.     routine does not modify any data passed in, it does neither
  357.     attach the menu created to the LayoutHandle passed in,
  358.     nor does it change the NewMenu table.
  359.  
  360.  
  361.     2.7 Localization
  362.  
  363.     All object and menu creation routines support localization via
  364.     a Hook callback interface, i.e. you can pass a pointer to an
  365.     initialized Hook structure to LT_CreateHandleTags() which will
  366.     later be used to supply label and list text for objects
  367.     created. The Hook callback routine is called in the following
  368.     fashion:
  369.  
  370.        String = HookFunc(struct Hook *Hook,struct LayoutHandle *Handle,LONG ID)
  371.          D0                            A0                         A2        A1
  372.  
  373.     Or in other words: a locale string ID is passed in, the routine is supposed
  374.     to look up the string to match this ID and to return it.
  375.  
  376.  
  377.     2.8 Object types to generate IDCMP_IDCMPUPDATE events
  378.  
  379.     Certain objects convey extra information which is merged into the `fake'
  380.     input stream passed to the client calling LT_HandleInput(). These objects
  381.     are:
  382.  
  383.        STRING_KIND
  384.        TEXT_KIND
  385.        PALETTE_KIND
  386.  
  387.           The user pressed the `select' button which belongs
  388.           to this gadget. The MsgGadget pointer indicates the
  389.           STRING_KIND/TEXT_KIND/PALETTE_KIND object the `select'
  390.           button belongs to.
  391.  
  392.        LISTVIEW_KIND
  393.  
  394.           The user double-clicked on an entry. The entry number
  395.           is returned in the MsgCode variable. The MsgGadget
  396.           pointer indicates the LISTVIEW_KIND object the user
  397.           has clicked on.
  398.  
  399.  
  400.     2.9 Keystroke activation
  401.  
  402.     Unless forbidden via the the LA_NoKey tag item the user interface
  403.     code will pick the keyboard shortcuts for all gadgets on its own.
  404.     The currently active global console keymap will be checked at the
  405.     time when LT_Init() is called in order to make sure subsequent
  406.     calls to LT_Build() will use only keys the user can press on
  407.     the keyboard. Double-dead keys are also excluded from the
  408.     table created. This avoids problems with gadget labels such as
  409.     "éééé" which would require the user to hit two keys in a row to
  410.     activate the gadget.
  411.        If the window created happens to feature a close gadget
  412.     pressing the `Esc' key will cause the client to receive
  413.     an IDCMP_CLOSEWINDOW event.
  414.        A single LISTVIEW_KIND object may receive special treatment
  415.     if the LALV_CursorKey tag is used: the user will be able to
  416.     operate the listview using the cursor keys. Note: this
  417.     will also keep the user interface code from choosing a
  418.     special keystroke from the gadget label.
  419.        The user will be able to operate a single BUTTON_KIND
  420.     object using the return key if the LABT_ReturnKey tag is
  421.     used. A recessed frame will be drawn around the button hit
  422.     box to indicate its special status.
  423.        Pressing the Tab key can be bound to operate a cycle or
  424.     mx kind object.
  425.  
  426.     3. Credits
  427.  
  428.     The original design is based upon the user interface layout code used by
  429.     `term' 3.1. I put the first version of the layout routines together back
  430.     in Summer 1993 when I wanted to write the follow-up to `term' v3.4.
  431.  
  432.     Martin Taillefer rewrote large parts of the code, added new routines and
  433.     generally improved the performance of the layout process. I owe Martin
  434.     much for the ideas he put into the library.
  435.  
  436.     Kai Iske, Christoph Feck, Stefan Becker, Michael Barsoom, Sven Stullich
  437.     and Mark Ritter helped to iron out the remaining bugs and piled up bug
  438.     reports and enhancement requests.
  439.  
  440. gtlayout.library/--version--                     gtlayout.library/--version--
  441.  
  442.    NOTES
  443.     This document describes gtlayout.library v5.12 or higher. Do not assume that
  444.     previous library releases support the same features.
  445.  
  446. gtlayout.library/LT_Activate                     gtlayout.library/LT_Activate
  447.  
  448.    NAME
  449.     LT_Activate -- Activate a string type gadget.
  450.  
  451.    SYNOPSIS
  452.     LT_Activate(Handle,ID);
  453.                   A0   D0
  454.  
  455.     VOID LT_Activate(LayoutHandle *,LONG);
  456.  
  457.    FUNCTION
  458.     The equivalent to intuition.library/ActivateGadget().
  459.  
  460.    INPUTS
  461.     Handle - Pointer to LayoutHandle structure.
  462.  
  463.     ID - ID of Gadget to activate.
  464.  
  465.    RESULT
  466.     none
  467.  
  468.    SEE ALSO
  469.     intuition.library/ActivateGadget
  470.  
  471. gtlayout.library/LT_BeginRefresh             gtlayout.library/LT_BeginRefresh
  472.  
  473.    NAME
  474.     LT_BeginRefresh -- Optimized window refreshing
  475.  
  476.    SYNOPSIS
  477.     LT_BeginRefresh(Handle)
  478.                       A0
  479.  
  480.    FUNCTION
  481.     If you wish to handle window refreshing all on your own, you
  482.     might want to use the LT_BeginRefresh...LT_EndRefresh pair
  483.     in your program. By default the user interface layout engine
  484.     will automatically intercept IDCMP_REFRESHWINDOW events and
  485.     react to them accordingly.
  486.  
  487.    INPUTS
  488.     Handle - Pointer to a LayoutHandle structure.
  489.  
  490.    RESULT
  491.     none
  492.  
  493.    SEE ALSO
  494.     intuition.library/BeginRefresh
  495.     intuition.library/EndRefresh
  496.     gtlayout.library/LT_EndRefresh
  497.  
  498. gtlayout.library/LT_BuildA                         gtlayout.library/LT_BuildA
  499.  
  500.    NAME
  501.     LT_BuildA -- turn the user interface specs into a window
  502.                  and gadgets.
  503.  
  504.    SYNOPSIS
  505.     Window = LT_BuildA(Handle,Tags);
  506.       D0                 A0    A1
  507.  
  508.     struct Window *LT_BuildA(LayoutHandle *,struct TagItem *);
  509.  
  510.     Window = LT_Build(Handle,...);
  511.  
  512.     struct Window *LT_Build(LayoutHandle *,...);
  513.  
  514.    FUNCTION
  515.     This is the big one. After building up a user interface specification
  516.     using LT_NewA() a call to LT_BuildA() will finally lay out the single
  517.     user interface elements, open a window and put the gadgets, etc.
  518.     inside.
  519.  
  520.     The code tries to fit all the gadgets into the window, but if it
  521.     runs out of space it will fall back to a different font and
  522.     rescale the user interface objects to match it. It will first
  523.     fall back onto the system default font. If unsuccessful it will
  524.     as a last resort try to use topaz.font/8.
  525.  
  526.     To make it easier to distinguish between different handles that
  527.     share the same Window->UserPort, the Window->UserData pointer
  528.     will point to the LayoutHandle that created it (V13).
  529.  
  530.         NOTE: Earlier library releases did not support this feature,
  531.             so be prepared to deal with Window->UserData == NULL.
  532.  
  533.    INPUTS
  534.     Handle - Pointer to a LayoutHandle structure.
  535.  
  536.     Tags - Pointer to TagItem list controlling window
  537.         and layout attributes.
  538.  
  539.  
  540.     All the tag values given are passed straight away to OpenWindowTags(),
  541.     see intuition.doc for more information.
  542.  
  543.     In addition to this a number of private tag values are supported:
  544.  
  545.     LAWN_Menu (struct Menu *) - The menu to attach to the window. The
  546.         IDCMP flags will be updated to include IDCMP_MENUPICK if this
  547.         tag is used.
  548.  
  549.     LAWN_MenuTemplate (struct NewMenu *) - A list of filled-in
  550.         NewMenu structures which will get passed straight through
  551.         to LT_NewMenuTemplate(). If a menu could be created, it will
  552.         be attached to the window. LT_DeleteHandle() will then later
  553.         automatically dispose of the menu. Please note that the window
  554.         may fail to open due to the menu layout going wrong. Separate
  555.         calls to LT_NewMenuTemplate() and LT_Build() may be a better
  556.         approach since it is easier to find out which process went
  557.         wrong. You will find a pointer to the menu attached to the
  558.         LayoutHandle in LayoutHandle->Menu. Please note that this
  559.         entry only exists in LayoutHandles created by gtlayout.library
  560.         v13 or higher. (V13)
  561.  
  562.             NOTE: This tag effectively overrides LAWN_Menu.
  563.  
  564.     LAWN_MenuTags (struct TagItem *) - A list of TagItems which
  565.         will get passed straight through to LT_NewMenuTagList().
  566.         Even if you don't ask for it, LT_Build() will pass
  567.         "LAMN_Handle,<Handle>" in for you, so any additional tags
  568.         specifying screen, fonts, etc. will be overridden. If a menu
  569.         could be created, it will be attached to the window.
  570.         LT_DeleteHandle() will then later automatically dispose of the
  571.         menu. Please note that the window may fail to open due to the
  572.         menu layout going wrong. Separate calls to LT_NewMenuTagList()
  573.         and LT_Build() may be a better approach since it is easier to
  574.         find out which process went wrong. You will find a pointer to the
  575.         menu attached to the LayoutHandle in LayoutHandle->Menu. Please note
  576.         that this entry only exists in LayoutHandles created by
  577.         gtlayout.library v13 or higher. (V13)
  578.  
  579.             NOTE: This tag effectively overrides LAWN_Menu and has
  580.                   precedence over LAWN_MenuTemplate.
  581.  
  582.     LAWN_UserPort (struct MsgPort *) - The MsgPort to use as the
  583.         window user port. The MsgPort will be attached using the
  584.         common ModifyIDCMP() method, closing the window will
  585.         first remove and reply all pending messages at this port.
  586.  
  587.     LAWN_Left (LONG) - The left edge position the window is to use.
  588.         This effectively overrides any horizontal alignment flags.
  589.  
  590.             NOTE: the code may choose to ignore this value if it finds
  591.                 that the window will not fit onto the screen unless
  592.                 the left edge position is changed.
  593.  
  594.     LAWN_Top (LONG) - The top edge position the window is to use.
  595.         This effectively overrides any vertical alignment flags.
  596.  
  597.             NOTE: the code may choose to ignore this value if it finds
  598.                 that the window will not fit onto the screen unless
  599.                 the top edge position is changed.
  600.  
  601.     LAWN_Zoom (BOOL) - Adds a zoom gadget to the window. Clicking
  602.         on this gadget will cause the window to shrink/zoom back
  603.         to its original position. This differs from the WA_Zoom
  604.         tag behaviour. When the window zooms back to its original
  605.         position the gadgets are automatically refreshed.
  606.         Default: FALSE
  607.  
  608.     LAWN_MaxPen (LONG) - The maximum rendering pen index your code
  609.         will use. Since you are -- with some restrictions -- allowed
  610.         to render into the window created you may want to avoid
  611.         silly side effects if drawing images or other colourful
  612.         textures which do not share the common user interface colours.
  613.         By default the layout code will change the maximum rendering
  614.         pen number for the window to include only the user interface
  615.         pen colours. This can, but need not disturb your own private
  616.         window rendering.
  617.         Look up graphics.library/SetMaxPen for more information.
  618.         Default: determined by looking up Screen->DrawInfo.dri_Pens
  619.  
  620.     LAWN_BelowMouse (BOOL) - This instructs the layout routine to
  621.         centre the window created -- if possible -- below the
  622.         mouse pointer. This effectively ignores any left edge,
  623.         top edge or alignment settings.
  624.         Default: FALSE
  625.  
  626.     LAWN_MoveToWindow (BOOL) - When the window is finally open the
  627.         user interface code will try to make sure the entire window
  628.         is visible on the screen, this may involve moving the
  629.         currently visible portion of an autoscrolling screen.
  630.         Default: TRUE
  631.  
  632.     LAWN_AutoRefresh (BOOL) - Handle IDCMP_REFRESHWINDOW events
  633.         automatically.
  634.         Default: TRUE
  635.  
  636.     LAWN_HelpHook (struct Hook *) - Hook code to invoke when the user
  637.         presses the "Help" key. See gtlayout.h for more information.
  638.         Default: NULL
  639.  
  640.     LAWN_Parent (struct Window *) - Parent window to centre the child
  641.         window in.
  642.         Default: NULL
  643.  
  644.     LAWN_BlockParent (BOOL) - Lock the parent window via LT_LockWindow()
  645.         until the child window is closed.
  646.  
  647.             NOTE: requires LAWN_Parent attribute.
  648.  
  649.         Default: FALSE
  650.  
  651.     LAWN_SmartZoom (BOOL) - Attach a zoom gadget to the window created.
  652.         When in zoomed state, the window will be as small as possible,
  653.         showing only the window title and window gadgets:
  654.  
  655.             NOTE: this tag implies LAWN_Zoom,TRUE
  656.  
  657.         Default: FALSE
  658.  
  659.     LAWN_Title (STRPTR) - The window title to use. Use this tag in
  660.         place of WA_Title or you will break the layout code.
  661.         Default: no title
  662.  
  663.     LAWN_Bounds (struct IBox *) - Bounds to centre the window in.
  664.         Default: NULL
  665.  
  666.     LAWN_ExtraWidth (LONG) - Extra width to add into the calculation
  667.         when opening the window.
  668.         Default: 0
  669.  
  670.     LAWN_ExtraHeight (LONG) - Extra height to add into the calculation
  671.         when opening the window.
  672.         Default: 0
  673.  
  674.     LAWN_IDCMP (ULONG) - Use this tag in place of WA_IDCMP or you
  675.         will break the object handling code.
  676.  
  677.     LAWN_AlignWindow (UWORD) - Alignment information for the window, must
  678.         be a mask made from the following bit values:
  679.  
  680.             ALIGNF_RIGHT - Align to screen right edge
  681.             ALIGNF_LEFT - Align to screen left edge
  682.             ALIGNF_TOP - Align to screen top edge
  683.             ALIGNF_BOTTOM - Align to screen bottom edge
  684.  
  685.         Unless forbidden (such as by passing ALIGNF_RIGHT|ALIGNF_TOP)
  686.         the window will be centered horizontally and/or vertically.
  687.  
  688.     LAWN_FlushLeft (BOOL) - Add no horizontal space surrounding the
  689.         objects the windows will hold. (V10)
  690.  
  691.     LAWN_FlushTop (BOOL) - Add no vertical space surrounding the
  692.         objects the windows will hold. (V10)
  693.  
  694.     LAWN_Show (BOOL) - Make the window visible when it is opened;
  695.         this may involve depth-arranging screens. (V10)
  696.            Default: FALSE
  697.  
  698.     LAWN_NoInitialRefresh (BOOL) - If set to TRUE, adds the
  699.         gadgets, but does not draw the window imagery. You need
  700.         to draw them later by calling gtlayout.library/LT_Refresh.
  701.         Default: FALSE
  702.  
  703.     LAWN_LimitWidth (UWORD) - Limit the width of the window to this
  704.         value. (V35)
  705.  
  706.     LAWN_LimitHeight (UWORD) - Limit the height of the window to this
  707.         value. (V35)
  708.  
  709.     LAWN_UserData (APTR) - Store this pointer with the Window information.
  710.         you can later retrieve it with the LT_GetWindowUserData()
  711.         call (V39).
  712.  
  713.    RESULT
  714.     Window - Pointer to a Window structure.
  715.  
  716.    SEE ALSO
  717.        gtlayout.library/LT_Refresh
  718.        gtlayout.library/LT_GetWindowUserData
  719.        intuition.library/OpenWindow
  720.        intuition.library/OpenWindowTagList
  721.  
  722. gtlayout.library/LT_CatchUpRefresh         gtlayout.library/LT_CatchUpRefresh
  723.  
  724.    NAME
  725.     LT_CatchUpRefresh -- Repair the display after missing the
  726.                          Window refresh message (V34).
  727.  
  728.    SYNOPSIS
  729.     LT_CatchUpRefresh(Handle)
  730.                         A0
  731.  
  732.     VOID LT_CatchUpRefresh(LayoutHandle *);
  733.  
  734.    FUNCTION
  735.     In case an application missed an IDCMP_REFRESHWINDOW event
  736.     the display may be damaged and in need of repair. This can
  737.     happen if the ASL requester is attached to the window,
  738.     sharing its IDCMP with the window. Any refresh events will then
  739.     go straight to nil. Call this routine if you believe that
  740.     you missed a refresh event. The display will be repaired only
  741.     if it is in need of repair, so there is no harm in calling it
  742.     if not actually necessary.
  743.  
  744.    INPUTS
  745.     Handle - Pointer to a LayoutHandle structure.
  746.  
  747.    RESULT
  748.     none
  749.  
  750.    SEE ALSO
  751.     gtlayout.library/LT_BeginRefresh
  752.     intuition.library/BeginRefresh
  753.     intuition.library/EndRefresh
  754.  
  755. gtlayout.library/LT_CreateHandleTagListtlayout.library/LT_CreateHandleTagList
  756.  
  757.    NAME
  758.     LT_CreateHandleTagList -- Allocate auxilary data required by LT_New()
  759.                               and LT_BuildA().
  760.  
  761.    SYNOPSIS
  762.     Handle = LT_CreateHandleTagList(Screen,Tags);
  763.       D0                              A0    A1
  764.  
  765.     LayoutHandle *LT_CreateHandleTagList(struct Screen *,struct TagItem *);
  766.  
  767.     Handle = LT_CreateHandleTags(Screen,...);
  768.  
  769.     struct LayoutHandle *LT_CreateHandleTags(struct Screen *,...);
  770.  
  771.    FUNCTION
  772.     Memory is allocated, tables are set up and data is collected
  773.     on a screen a user interface is to be opened on. This
  774.     involves calculating the screen font parameters.
  775.  
  776.    INPUTS
  777.     Screen - Pointer to the screen the user interface is to
  778.         use. Passing NULL will cause the default public
  779.         screen to be used.
  780.  
  781.             NOTE: if NULL is passed the default public screen
  782.                 will stay locked until LT_DeleteHandle()
  783.                 is called.
  784.  
  785.     Tags - Tag values to control certain aspects of the
  786.         user interface created.
  787.  
  788.  
  789.     Valid tags include:
  790.  
  791.     LAHN_AutoActivate (BOOL) - Set to TRUE if you want the interface
  792.         to always keep a string gadget active if possible. Hitting
  793.         the return key will then cause the next following string
  794.         gadget to get activated, either cycling through all the
  795.         string gadgets available or stopping at the next string
  796.         gadget to have the LAST_LastGadget attribute set.
  797.         Default: TRUE
  798.  
  799.     LAHN_RawKeyFilter (BOOL) - Discard unprocessed IDCMP_RAWKEY
  800.         events. (V13)
  801.         Default: TRUE
  802.  
  803.     LAHN_UserData (APTR) - Store user specific data in the
  804.         LayoutHandle->UserData entry.
  805.  
  806.             NOTE: This tag requires gtlayout.library v9 and the
  807.                 corresponding entry in the LayoutHandle exists
  808.                 only under gtlayout.library v9 and up. *NEVER*
  809.                 write to this entry, use LT_SetAttributes()
  810.                 instead.
  811.  
  812.     LAHN_LocaleHook (struct Hook *) - The hook to call when
  813.         locale string IDs are to be mapped to strings. The
  814.         hook function is called with the following parameters:
  815.  
  816.         String = HookFunc(struct Hook *Hook,struct LayoutHandle *Handle,
  817.           D0                            A0                         A2
  818.                           LONG ID)
  819.                                A1
  820.  
  821.         The function is to look up the string associated with the ID
  822.         passed in and return the string.
  823.         Default: no locale hook
  824.  
  825.     LAHN_TextAttr (struct TTextAttr *) - The text font to use when
  826.         creating the gadgets and objects.
  827.         Default: Screen->Font
  828.  
  829.     LAHN_CloningPermitted (BOOL) - If a window will not fit onto the
  830.         screen the user interface is intended for, the layout engine
  831.         will scale the interface data down while stepping down in
  832.         font size. If all this fails, the engine will open a custom
  833.         screen for the window; this process is called "cloning".
  834.         The LAHN_CloningPermitted tag controls whether the engine will
  835.         actually try to open the custom screen or just return NULL
  836.         when LT_Build fails.
  837.         Default: TRUE
  838.  
  839.     LAHN_EditHook (struct Hook *) - You can specify a default string
  840.         gadget editing hook to be used for all following string
  841.         gadgets. Your hook should obey the same rules that apply
  842.         to hooks passed via GTST_EditHook/GTIN_EditHook.
  843.         Default: NULL
  844.  
  845.     LAHN_ExactClone (BOOL) - This tag works in conjunction with the
  846.         LAHN_CloningPermitted tag. By default the layout engine will
  847.         try to replicate only the basic characteristics of the
  848.         screen the window was intended to open on. This may result
  849.         in a screen which uses less colours than the original
  850.         screen. You can force the engine to make an almost exact
  851.         clone of the original screen by passing the LAHN_ExactClone
  852.         tag with a value of TRUE.
  853.         Default: FALSE
  854.  
  855.     LAHN_MenuGlyphs (BOOL) - This tag will make the layout engine
  856.         fill in the AmigaGlyph and CheckGlyph entries of the
  857.         LayoutHandle if running under Kickstart 3.0 or higher.
  858.         The corresponding images will be scaled to fit the actual
  859.         screen aspect ratio values and can later be used for
  860.         menu layout.
  861.         Default: FALSE
  862.  
  863.     LAHN_Parent (struct Window *) - You can pass a pointer to the
  864.         parent window of the window you intend to open using
  865.         the user interface layout engine. The new window will
  866.         open inside the boundaries of the parent window. If the
  867.         size does not fit, it will be opened centered over the
  868.         parent window.
  869.         Default: NULL
  870.  
  871.     LAHN_BlockParent (BOOL) - This tag works in conjunction with the
  872.         LAHN_Parent tag. If in effect, will block the parent window
  873.         via LT_LockWindow until the new window is closed, after
  874.         which the parent window is unlocked again.
  875.         Default: FALSE
  876.  
  877.     LAHN_SimpleClone (BOOL) - This tag works in conjunction with the
  878.         LAHN_CloningPermitted tag. It will make the layout engine
  879.         forget most information about the original screen the
  880.         user interface was intended for. In short, it will open a
  881.         simple default screen for the interface.
  882.         Default: FALSE
  883.  
  884.     LAHN_ExitFlush (BOOL) - When the LayoutHandle is finally disposed
  885.         of with LT_DeleteHandle() all variables maintained by the
  886.         input handling code will be flushed. For example, if you
  887.         would use the LA_STRPTR tag for STRING_KIND objects the
  888.         last string gadget contents would be copied into the buffer
  889.         pointed to by LA_STRPTR. If you do not want to use this
  890.         feature, disable it with "LAHN_ExitFlush,FALSE". (V9)
  891.         Default: TRUE
  892.  
  893.     LAHN_NoKeys (BOOL) - Use TRUE to tell the library not to pick
  894.         keyboard shortcuts all on its own. This works like calling
  895.         LT_New() for all objects with "LA_NoKey,TRUE,". (V26)
  896.  
  897.     LAHN_PubScreen (struct Screen *) - Pointer to public screen
  898.         window is to open on. Must be locked and open until you call
  899.         LT_Built().
  900.  
  901.     LAHN_PubScreenName (STRPTR) - Name of public screen to open window
  902.         on. The library will try to lock the named screen as soon as
  903.         you call LT_CreateHandle.
  904.  
  905.     LAHN_PubScreenFallBack (BOOL) - If the named public screen cannot
  906.         be found and you ask for it, the library will lock the default
  907.         public screen (default: TRUE).
  908.  
  909.     LAHN_TopGroupType (LONG) - Request that after creating the layout
  910.         handle, a layout group should be added to it. This can be
  911.         either a vertical or a horizontal group. You specify the type
  912.         using VERTICAL_KIND or HORIZONTAL_KIND (default: don't add
  913.         any group). (V45)
  914.  
  915.    RESULT
  916.     Handle - Pointer to a LayoutHandle structure.
  917.  
  918. gtlayout.library/LT_DeleteHandle             gtlayout.library/LT_DeleteHandle
  919.  
  920.    NAME
  921.     LT_DeleteHandle -- Release storage space allocated by
  922.                        LT_CreateHandleTagList, closing windows,
  923.                        removing gadgets, etc.
  924.  
  925.    SYNOPSIS
  926.     LT_DeleteHandle(Handle);
  927.                       A0
  928.  
  929.     VOID LT_DeleteHandle(LayoutHandle *);
  930.  
  931.    FUNCTION
  932.     Windows and gadgets created by LT_CreateHandleTagList()
  933.     are removed, any associated memory is deallocated.
  934.  
  935.    INPUTS
  936.     Handle - Pointer to a LayoutHandle structure created
  937.         by LT_CreateHandleTaglist(). Passing NULL is
  938.         harmless.
  939.  
  940.    RESULT
  941.     none
  942.  
  943.    SEE ALSO
  944.     gtlayout.library/CreateHandleTagList
  945.  
  946. gtlayout.library/LT_DeleteWindowLock     gtlayout.library/LT_DeleteWindowLock
  947.  
  948.    NAME
  949.     LT_DeleteWindowLock -- Remove all locks from a window
  950.  
  951.    SYNOPSIS
  952.     LT_DeleteWindowLock(Window);
  953.                           A0
  954.  
  955.     VOID LT_DeleteWindowLock(struct Window *);
  956.  
  957.    FUNCTION
  958.     Before closing a locked window you should call this routine
  959.     which will remove all outstanding locks from it.
  960.  
  961.    INPUTS
  962.     Window - Pointer to window structure; passing NULL is
  963.     harmless.
  964.  
  965.    RESULT
  966.     none
  967.  
  968. gtlayout.library/LT_DisposeMenu               gtlayout.library/LT_DisposeMenu
  969.  
  970.    NAME
  971.     LT_DisposeMenu -- Release storage space allocated by
  972.                       LT_NewMenuTemplate or LT_NewMenuTagList (V11)
  973.  
  974.    SYNOPSIS
  975.     LT_DisposeMenu(Menu)
  976.                     A0
  977.  
  978.     VOID LT_DisposeMenu(struct Menu *);
  979.  
  980.    FUNCTION
  981.     Menus and MenuItems allocated by LT_NewMenuTemplate or
  982.     LT_NewMenuTagList are deallocated.
  983.  
  984.    INPUTS
  985.     Menu - Pointer to Menu structure as returned by
  986.         LT_NewMenuTemplate or LT_NewMenuTagList. Passing
  987.         NULL is harmless.
  988.  
  989.    RESULT
  990.     none
  991.  
  992.    SEE ALSO
  993.     gtlayout.library/LT_NewMenuTagList
  994.     gtlayout.library/LT_NewMenuTemplate
  995.  
  996. gtlayout.library/LT_EndGroup                     gtlayout.library/LT_EndGroup
  997.  
  998.    NAME
  999.     LT_EndGroup -- end a group declaration.
  1000.  
  1001.    SYNOPSIS
  1002.     LT_EndGroup(Handle);
  1003.                  A0
  1004.  
  1005.     VOID LT_EndGroup(LayoutHandle *);
  1006.  
  1007.    FUNCTION
  1008.       This is just a short form of
  1009.  
  1010.            LT_New(Handle,
  1011.                LA_Type, END_KIND,
  1012.            TAG_DONE);
  1013.  
  1014.       It helps to save (some) space.
  1015.  
  1016.    INPUTS
  1017.         Handle - Pointer to LayoutHandle.
  1018.  
  1019.    RESULT
  1020.     none
  1021.  
  1022.    SEE ALSO
  1023.     gtlayout.library/LT_New
  1024.  
  1025. gtlayout.library/LT_EndRefresh                 gtlayout.library/LT_EndRefresh
  1026.  
  1027.    NAME
  1028.     LT_EndRefresh -- Optimized window refreshing
  1029.  
  1030.    SYNOPSIS
  1031.     LT_EndRefresh(Handle)
  1032.                     A0
  1033.  
  1034.     VOID LT_EndRefresh(LayoutHandle *);
  1035.  
  1036.    FUNCTION
  1037.     If you wish to handle window refreshing all on your own, you
  1038.     might want to use the LT_BeginRefresh...LT_EndRefresh pair
  1039.     in your program. By default the user interface layout engine
  1040.     will automatically intercept IDCMP_REFRESHWINDOW events and
  1041.     react to them accordingly.
  1042.  
  1043.    INPUTS
  1044.     Handle - Pointer to a LayoutHandle structure.
  1045.  
  1046.    RESULT
  1047.     none
  1048.  
  1049.    SEE ALSO
  1050.     gtlayout.library/LT_BeginRefresh
  1051.     intuition.library/BeginRefresh
  1052.     intuition.library/EndRefresh
  1053.  
  1054. gtlayout.library/LT_Exit                             gtlayout.library/LT_Exit
  1055.  
  1056.    NAME
  1057.     LT_Exit -- Clean up user interface allocations
  1058.  
  1059.    SYNOPSIS
  1060.     LT_Exit();
  1061.  
  1062.     VOID LT_Exit(VOID);
  1063.  
  1064.    FUNCTION
  1065.     When you are finished with user interface creation and
  1066.     do not not need the code any more you should call this
  1067.     routine. It will free all the memory allocated by
  1068.     LT_Init(), close libraries, etc.
  1069.  
  1070.    INPUTS
  1071.     none
  1072.  
  1073.    RESULT
  1074.     none
  1075.  
  1076.    NOTES
  1077.     This function is not present in the shared library, only
  1078.     in the link library. You need not and cannot invoke it in
  1079.     the shared library.
  1080.  
  1081.    SEE ALSO
  1082.     gtlayout.library/LT_Init
  1083.  
  1084. gtlayout.library/LT_FindMenuCommand       gtlayout.library/LT_FindMenuCommand
  1085.  
  1086.    NAME
  1087.     LT_FindMenuCommand -- Get the menu/submenu item associated
  1088.                           with a rawkey event (V11)
  1089.  
  1090.    SYNOPSIS
  1091.     Item = LT_FindMenuCommand(Menu,Code,Qualifier,Gadget)
  1092.      D0                        A0  D0       D0      A1
  1093.  
  1094.     struct MenuItem *LT_FindMenuCommand(struct Menu *,
  1095.  
  1096.                          UWORD,ULONG,struct Gadget *);
  1097.  
  1098.    FUNCTION
  1099.     With the IntuiMessage data copied from a type IDCMP_RAWKEY message
  1100.     tries to find the MenuItem the event referred to.
  1101.  
  1102.    INPUTS
  1103.     Menu - Pointer to Menu structure as returned by LT_NewMenuTagList.
  1104.  
  1105.     Code - Value copied from IntuiMessage->Code
  1106.  
  1107.     Qualifier - Value copied from IntuiMessage->Qualifier
  1108.  
  1109.     Gadget - Value copied from IntuiMessage->IAddress
  1110.  
  1111.    RESULT
  1112.     Item - Pointer to the struct MenuItem * in question or NULL
  1113.         if none could be found
  1114.  
  1115.    SEE ALSO
  1116.     gtlayout.library/LT_NewMenuTagList
  1117.  
  1118. gtlayout.library/LT_GetAttributesA         gtlayout.library/LT_GetAttributesA
  1119.  
  1120.    NAME
  1121.     LT_GetAttributesA -- Inquire information on a gadget.
  1122.  
  1123.    SYNOPSIS
  1124.     Value = LT_GetAttributesA(Handle,ID,Tags);
  1125.       D0                        A0   D0  A1
  1126.  
  1127.     LONG LT_GetAttributesA(LayoutHandle *,LONG ID,struct TagItem *);
  1128.  
  1129.     Value = LT_GetAttributes(Handle,ID,...);
  1130.  
  1131.     LONG LT_GetAttributes(LayoutHandle *,LONG ID,...);
  1132.  
  1133.    FUNCTION
  1134.     All objects created by the user interface layout code posess
  1135.     certain unique properties. The LT_GetAttributes() function will
  1136.     will inquire this information and return it. The implementation
  1137.     differs from gadtools.library/GT_GetGadgetAttrs in that you
  1138.     can inquire only a small subset of the object properties possible
  1139.     via the taglist passed in.
  1140.  
  1141.    INPUTS
  1142.     Handle - Pointer to LayoutHandle structure.
  1143.  
  1144.     ID - ID number of the object to inquire information about. This
  1145.         is the same value you passed via LA_ID to LT_New() when
  1146.         you created this object.
  1147.  
  1148.     Tags - TagItem list to receive information about the object
  1149.         in question.
  1150.  
  1151.  
  1152.     LA_Left (LONG *) - Left edge of object.
  1153.  
  1154.     LA_Top (LONG *) - Top edge of object.
  1155.  
  1156.     LA_Width (LONG *) - Width of object.
  1157.  
  1158.     LA_Height (LONG *) - Height of object.
  1159.  
  1160.     LA_Chars (LONG *) - Width of object measured in character
  1161.         widths. (V9)
  1162.  
  1163.     LA_Lines (LONG *) - Height of object measured in character
  1164.         heights. (V9)
  1165.  
  1166.     LA_LabelLeft (LONG *) - Left edge of label text. (V9)
  1167.  
  1168.     LA_LabelTop (LONG *) - Top edge of label text. (V9)
  1169.  
  1170.     LABO_Object (Object *) - Returns a pointer to the BOOPSI object
  1171.         the BOOPSI_KIND object is based upon. (V10)
  1172.  
  1173.             NOTE: Don't unlink the object or dispose of it or
  1174.                 terrible things are bound to happen.
  1175.  
  1176.     LAST_CursorPosition (LONG *) - Current position of the cursor
  1177.         in STRING_KIND and FRACTION_KIND objects. (V
  1178.  
  1179.    RESULT
  1180.     The result depends on the object type:
  1181.  
  1182.         VERTICAL_KIND:
  1183.         HORIZONTAL_KIND:
  1184.  
  1185.             active page
  1186.  
  1187.         SCROLLER_KIND:
  1188.  
  1189.             current GTSC_Top value
  1190.  
  1191.         TAPEDECK_KIND:
  1192.  
  1193.             current LATD_Pressed value
  1194.  
  1195.         LEVEL_KIND:
  1196.  
  1197.             current LAVL_Level state
  1198.  
  1199.         CHECKBOX_KIND:
  1200.  
  1201.             current GTCB_Checked state
  1202.  
  1203.         LISTVIEW_KIND:
  1204.  
  1205.             current GTLV_Selected state
  1206.  
  1207.         MX_KIND:
  1208.  
  1209.             current GTMX_Active state
  1210.  
  1211.         CYCLE_KIND:
  1212.  
  1213.             current GTCY_Active state
  1214.  
  1215.         POPUP_KIND:
  1216.  
  1217.             current LAPU_Active state
  1218.  
  1219.         TAB_KIND:
  1220.  
  1221.             current LATB_Active state
  1222.  
  1223.         PALETTE_KIND:
  1224.  
  1225.             current GTPA_Color state
  1226.  
  1227.         SLIDER_KIND:
  1228.  
  1229.             current GTSL_Level state
  1230.  
  1231.         GAUGE_KIND:
  1232.  
  1233.             current LAGA_Percent state
  1234.  
  1235.         STRING_KIND:
  1236.  
  1237.             pointer to current string
  1238.  
  1239.         PASSWORD_KIND:
  1240.  
  1241.             pointer to current string
  1242.  
  1243.         INTEGER_KIND:
  1244.  
  1245.             number currently entered
  1246.  
  1247.         BOOPSI_KIND:
  1248.  
  1249.             whatever the object thinks is its
  1250.             current value
  1251.  
  1252. gtlayout.library/LT_GetCode                       gtlayout.library/LT_GetCode
  1253.  
  1254.    NAME
  1255.     LT_GetCode -- Easy raw key event to ANSI conversion.
  1256.  
  1257.    SYNOPSIS
  1258.     Key = LT_GetCode(Qualifier,Class,Code,Gadget);
  1259.      D0                  D0     D1    D2    A0
  1260.  
  1261.     LONG LT_GetCode(ULONG,ULONG,UWORD,struct Gadget *);
  1262.  
  1263.    FUNCTION
  1264.     The user interface layout engine can convert IDCMP_RAWKEY
  1265.     events into ANSI codes. Pass in the data you copied from
  1266.     the IntuiMessage here.
  1267.  
  1268.    INPUTS
  1269.     Qualifier - Copied from IntuiMessage->Qualifier
  1270.  
  1271.     Class - Copied from IntuiMessage->Class
  1272.  
  1273.     Code - Copied from IntuiMessage->Code
  1274.  
  1275.     Gadget - Copied from IntuiMessage->IAddress
  1276.  
  1277.    RESULT
  1278.     Key - ANSI code generated from the input data
  1279.         or -1 if no such code was to be generated.
  1280.  
  1281. gtlayout.library/LT_GetIMsg                       gtlayout.library/LT_GetIMsg
  1282.  
  1283.    NAME
  1284.     LT_GetIMsg -- Retrieve the next pending IntuiMessage
  1285.                   from the window associated with a
  1286.                   LayoutHandle.
  1287.  
  1288.    SYNOPSIS
  1289.     IntuiMessage = LT_GetIMsg(Handle);
  1290.          D0                     A0
  1291.  
  1292.     struct IntuiMessage *LT_GetIMsg(LayoutHandle *);
  1293.  
  1294.    FUNCTION
  1295.     This routine will handle most of the input loop for
  1296.     you. Just pass the pointer to the layout handle in,
  1297.     check if the result code is non-null, copy the data
  1298.     you need and reply the message via LT_ReplyIMsg().
  1299.  
  1300.     You will still need to wait for new input, as LT_GetIMsg
  1301.     will poll the MsgPort of the window.
  1302.  
  1303.     LT_GetIMsg() will try its best to distinguish between
  1304.     different LayoutHandles sharing the same Window->UserPort.
  1305.     If it finds that the window the message was sent to is
  1306.     using a different LayoutHandle, it will switch to using
  1307.     this handle (V13).
  1308.  
  1309.    INPUTS
  1310.     Handle - Pointer to LayoutHandle structure
  1311.  
  1312.    RESULT
  1313.     IntuiMessage - Pointer to IntuiMessage structure
  1314.  
  1315.    NOTES
  1316.     You *must not* make any assumptions about the contents
  1317.     of the IntuiMessage structure except for the following
  1318.     entries:
  1319.  
  1320.        Class
  1321.        Code
  1322.        Qualifier
  1323.        IAddress
  1324.  
  1325.     When finished, you must dispose the IntuiMessage via
  1326.     LT_ReplyIMsg or memory will be lost which can never
  1327.     be reclaimed.
  1328.  
  1329.     DO NOT CALL LT_HandleInput() ON THE DATA YOU RECEIVE
  1330.     FROM LT_GetIMsg() AS LT_GetIMsg() ALREADY DOES ALL THE
  1331.     MAGIC LT_HandleInput() OTHERWISE WOULD NEED TO DO!
  1332.     IF YOU STILL DO CALL LT_HandleInput() ON THE DATA YOU
  1333.     WILL RECEIVE `GHOST' EVENTS.
  1334.  
  1335.    SEE ALSO
  1336.     gtlayout.library/LT_ReplyIMsg
  1337.  
  1338. gtlayout.library/LT_GetMenuItem               gtlayout.library/LT_GetMenuItem
  1339.  
  1340.    NAME
  1341.     LT_GetMenuItem -- Get the menu/submenu item associated with an ID (V11)
  1342.  
  1343.    SYNOPSIS
  1344.     Item = LT_GetMenuItem(Menu,ID)
  1345.      D0                    A0  D0
  1346.  
  1347.     struct MenuItem *LT_GetMenuItem(struct Menu *,ULONG);
  1348.  
  1349.    FUNCTION
  1350.     This routine scans through all menu items associated with the
  1351.     menu and returns a pointer to the item associated with the
  1352.     given ID value.
  1353.  
  1354.    INPUTS
  1355.     Menu - Pointer to Menu structure as returned by LT_NewMenuTagList.
  1356.  
  1357.     ID - Unique ID of the item to find.
  1358.  
  1359.    RESULT
  1360.     Item - Pointer to the struct MenuItem * in question or NULL
  1361.         if none could be found
  1362.  
  1363.    SEE ALSO
  1364.     gtlayout.library/LT_NewMenuTagList
  1365.  
  1366. gtlayout.library/LT_GetWindowUserData   gtlayout.library/LT_GetWindowUserData
  1367.  
  1368.    NAME
  1369.     LT_GetWindowUserData -- Obtain user data information associated
  1370.         with a Window created by gtlayout.library/LT_Build (V39).
  1371.  
  1372.    SYNOPSIS
  1373.     Data = LT_GetWindowUserData(Window,DefaultValue);
  1374.       D0                         A0        A1
  1375.  
  1376.     APTR LT_GetWindowUserData(struct Window *,APTR);
  1377.  
  1378.    FUNCTION
  1379.     You can tell the build process to store user data with the Window
  1380.     it creates. This can be used as a replacement for the Window->UserData
  1381.     pointer information which gtlayout.library uses for itself. If the
  1382.     Window you pass to this routine was created by gtlayout.library/LT_Build
  1383.     you will receive the user data pointer you passed in, otherwise the
  1384.     given default value will be returned.
  1385.  
  1386.    INPUTS
  1387.     Window - Pointer to a Window created by gtlayout.library/LT_Build
  1388.  
  1389.    RESULT
  1390.     Data - The user data pointer you provided for gtlayout.library/LT_Build
  1391.         with the LAWN_UserData tag or the default value if no such pointer
  1392.         was provided or this Window was not created by
  1393.         gtlayout.library/LT_Build.
  1394.  
  1395.     DefaultValue - If the window was not created by gtlayout.library/LT_Build
  1396.         this is the value you will receive as the function result.
  1397.  
  1398.    SEE ALSO
  1399.        gtlayout.library/LT_Build
  1400.  
  1401. gtlayout.library/LT_HandleInput               gtlayout.library/LT_HandleInput
  1402.  
  1403.    NAME
  1404.     LT_HandleInput -- Filter IntuiMessage data.
  1405.  
  1406.    SYNOPSIS
  1407.     LT_HandleInput(Handle,Qualifier,Class,Code,Gadget);
  1408.                      A0      D0      A1    A2    A3
  1409.  
  1410.     VOID LT_HandleInput(LayoutHandle *,ULONG,ULONG *,
  1411.                         UWORD *,struct Gadget **);
  1412.  
  1413.    FUNCTION
  1414.     In order to keep track of user interface actions, such as
  1415.     keys getting pressed, sliders getting moved, etc. your
  1416.     code is to call LT_HandleInput() with data copied from the
  1417.     IntuiMessage it has just received and replied.
  1418.  
  1419.    INPUTS
  1420.     Handle - Pointer to a LayoutHandle structure.
  1421.  
  1422.     Qualifier - The Qualifier value copied from the
  1423.         IntuiMessage structure.
  1424.  
  1425.     Class - Pointer to the ULONG variable which holds the
  1426.         value copied from the Class entry of the
  1427.         IntuiMessage structure.
  1428.  
  1429.     Code - Pointer to the UWORD variable which holds the
  1430.         value copied from the Code entry of the
  1431.         IntuiMessage structure.
  1432.  
  1433.     Gadget - Pointer to the Gadget value copied from the
  1434.         IAddress entry of the IntuiMessage structure.
  1435.  
  1436.    RESULT
  1437.     none
  1438.  
  1439.    EXAMPLE
  1440.     struct IntuiMessage *IntuiMessage;
  1441.     ULONG Qualifier,Class;
  1442.     UWORD Code;
  1443.     struct Gadget *Gadget;
  1444.  
  1445.     for(;;)
  1446.     {
  1447.         WaitPort(Window->UserPort);
  1448.  
  1449.         while(IntuiMessage = GT_GetIMsg(Window->UserPort))
  1450.         {
  1451.             Class = IntuiMessage->Class;
  1452.             Code = IntuiMessage->Code;
  1453.             Qualifier = IntuiMessage->Qualifier;
  1454.             Gadget = IntuiMessage->Gadget;
  1455.  
  1456.             GT_ReplyIMsg(IntuiMessage);
  1457.  
  1458.             LT_HandleInput(Handle,Qualifier,&Class,&Code,&Gadget);
  1459.         }
  1460.     }
  1461.  
  1462.    NOTES
  1463.     For BOOPSI_KIND objects keystroke activation may lead to
  1464.     unexpected results. Your application will hear a IDCMP_GADGETUP
  1465.     event, the IntuiMessage->Code value will hold the ANSI key
  1466.     code of the key the user pressed.
  1467.  
  1468.     Do not call this routine before you have actually
  1469.     replied the IntuiMessage received or weird things
  1470.     may happen. This is not a suggestion, it's a threat.
  1471.  
  1472. gtlayout.library/LT_Init                             gtlayout.library/LT_Init
  1473.  
  1474.    NAME
  1475.     LT_Init -- Initialize user interface code.
  1476.  
  1477.    SYNOPSIS
  1478.     LT_Init();
  1479.  
  1480.     VOID LT_Init(VOID);
  1481.  
  1482.    FUNCTION
  1483.     You need to initialize the user interface code only once,
  1484.     so it can set up its internals, open libraries, etc.
  1485.     The code has to be initialized before any user interface
  1486.     creation can take place.
  1487.  
  1488.    NOTES
  1489.     This function is not present in the shared library, only
  1490.     in the link library. You need not and cannot invoke it in
  1491.     the shared library.
  1492.  
  1493.    SEE ALSO
  1494.     gtlayout.library/LT_Exit
  1495.  
  1496. gtlayout.library/LT_LabelChars                 gtlayout.library/LT_LabelChars
  1497.  
  1498.    NAME
  1499.     LT_LabelChars -- Calculate the width of a a string
  1500.                      according to the user interface font
  1501.                      associated with a LayoutHandle.
  1502.  
  1503.    SYNOPSIS
  1504.     Length = LT_LabelChars(Handle,Label);
  1505.       D0                     A0    A1
  1506.  
  1507.     LONG LT_LabelChars(struct LayoutHandle *,STRPTR);
  1508.  
  1509.    FUNCTION
  1510.     Calculates the width of a string according to the user
  1511.     interface font used. The width is then converted to a number
  1512.     of characters suitable for using with the LA_Chars tag
  1513.     item when calling LT_New().
  1514.  
  1515.     You can pass multi-line label texts to this routine,
  1516.     it will calculate the maximum length of the single
  1517.     lines. (V12)
  1518.  
  1519.    INPUTS
  1520.     Handle - Pointer to LayoutHandle structure.
  1521.  
  1522.     Label - Pointer to string.
  1523.  
  1524.    RESULT
  1525.     Length - Number of characters that are considered
  1526.         equivalent to the string length in pixels.
  1527.  
  1528. gtlayout.library/LT_LabelWidth                 gtlayout.library/LT_LabelWidth
  1529.  
  1530.    NAME
  1531.     LT_LabelWidth -- Calculate the width of a string according
  1532.                      to the user interface font used.
  1533.  
  1534.    SYNOPSIS
  1535.     Width = LT_LabelWidth(Handle,Label);
  1536.       D0                    A0    A1
  1537.  
  1538.     LONG LT_LabelWidth(LayoutHandle *,STRPTR);
  1539.  
  1540.    FUNCTION
  1541.     This routine calculates the width of strings in
  1542.     terms of pixels according to the user interface
  1543.     font associated with the LayoutHandle.
  1544.  
  1545.     You can pass multi-line label texts to this routine,
  1546.     it will calculate the maximum length of the single
  1547.     lines. (V12)
  1548.  
  1549.    INPUTS
  1550.     Handle - Pointer to LayoutHandle structure.
  1551.  
  1552.    RESULT
  1553.     Width - Width of the text string in pixels.
  1554.  
  1555. gtlayout.library/LT_LayoutMenusA             gtlayout.library/LT_LayoutMenusA
  1556.  
  1557.    NAME
  1558.     LT_LayoutMenusA -- Create a menu according to a template.
  1559.  
  1560.    SYNOPSIS
  1561.     Menu = LT_LayoutMenusA(Handle,Template,Tags);
  1562.      D0                      A0     A1      A2
  1563.  
  1564.     struct Menu *LT_LayoutMenusA(LayoutHandle *,struct NewMenu *,
  1565.  
  1566.         struct TagItem *);
  1567.  
  1568.     Menu = LT_LayoutMenus(Handle,Template,...);
  1569.  
  1570.     struct Menu *LT_LayoutMenus(LayoutHandle *,struct NewMenu *,...);
  1571.  
  1572.    FUNCTION
  1573.     Unlike the corresponding routines in gadtools.library
  1574.     LT_LayoutMenusA() will both create and layout a menu.
  1575.     Also included is locale support.
  1576.  
  1577.    INPUTS
  1578.     Handle - Pointer to LayoutHandle structure.
  1579.  
  1580.     Template - Address of a ready-to-use NewMenu table to
  1581.         create the menu from.
  1582.  
  1583.     Tags - Tagitem list to control menu attributes
  1584.  
  1585.     Tags:
  1586.  
  1587.     LAMN_FirstLabel (LONG) - Locale ID of the first string to
  1588.         use as a menu title/item/subitem label. This tag
  1589.         works in conjunction with LA_LastLabel.
  1590.  
  1591.     LAMN_LastLabel (LONG) - Locale ID of the last string to
  1592.         use as a menu title/item/subitem label. This tag
  1593.         works in conjunction with LA_FirstLabel. The code
  1594.         will loop through FirstLabel..LastLabel and assign
  1595.         the corresponding locale text for each ID to the
  1596.         NewMenu.nm_Label entries. Labels which are already
  1597.         initialized with NM_BARLABEL are skipped.
  1598.  
  1599.     LAMN_LabelTable (LONG *) - Pointer to an array of IDs
  1600.         to use for building the menu labels. This requires
  1601.         that a locale hook is provided with the layout handle.
  1602.         The array is terminated by -1.
  1603.  
  1604.    RESULT
  1605.     Menu - Pointer to a Menu structure. You can free this
  1606.            using gadtools.library/FreeMenus().
  1607.  
  1608. gtlayout.library/LT_LevelWidth                 gtlayout.library/LT_LevelWidth
  1609.  
  1610.    NAME
  1611.     LT_LevelWidth -- Determine the maximum width of a SLIDER_KIND
  1612.                      level string.
  1613.  
  1614.    SYNOPSIS
  1615.     Index = LT_LevelWidth(Handle,FormatString,DispFunc,Min,Max,MaxWidth,
  1616.       D0                    A0        A1         A2     D0  D1    A3
  1617.  
  1618.                               MaxLen,FullCheck);
  1619.                                 A5      D2
  1620.  
  1621.     LONG LT_LevelWidth(LayoutHandle *,STRPTR,
  1622.                        LONG (*)(struct Gadget *,WORD),LONG,LONG,LONG *,
  1623.                        LONG *,BOOL);
  1624.  
  1625.    FUNCTION
  1626.     In order to make room for the level text displayed by a
  1627.     SLIDER_KIND object one needs to know how much space the
  1628.     longest level string will occupy. Otherwise, the level
  1629.     text may overwrite the gadget label text or the slider
  1630.     container. This routine will rattle through all possible
  1631.     slider settings (as given via the Min and the Max
  1632.     level values) and determine the longest label string
  1633.     according to the font used.
  1634.  
  1635.    INPUTS
  1636.     Handle - Pointer to a LayoutHandle structure, as returned by
  1637.         a call to LT_CreateHandleTags().
  1638.  
  1639.     FormatString - The sprintf() style formatting string to be used
  1640.         to format the slider level settings into text.
  1641.         This is the same string you would pass in via
  1642.         the GTSL_LevelFormat tag when creating the
  1643.         slider object.
  1644.         Default: "%lD" for systems which have locale.library
  1645.             installed, "%ld" otherwise.
  1646.  
  1647.     DispFunc - A pointer to the function to filter the slider level
  1648.         values. The result of this function will then be
  1649.         used to format a string into the slider level text.
  1650.         This is the same parameter you would pass in via
  1651.         the GTSL_DispFunc tag when creating the slider
  1652.         object.
  1653.  
  1654.             NOTE: the routine will be called with a NULL Gadget
  1655.                 parameter, make sure your code will handle
  1656.                 this nicely.
  1657.  
  1658.         Default: no display function
  1659.  
  1660.     Min - The smallest value the slider can be set to. This is
  1661.         same value you would pass in via GTSL_Min when creating
  1662.         the slider object.
  1663.  
  1664.     Max - The largest value the slider can be set to. This is
  1665.         same value you would pass in via GTSL_Max when creating
  1666.         the slider object.
  1667.  
  1668.     MaxWidth - Pointer to a place to store the width of the
  1669.         longest level string in pixels. If you pass
  1670.         in NULL instead of the address of a variable
  1671.         no harm will be done.
  1672.  
  1673.     MaxLen - Pointer to a place to store the length of the
  1674.         longest level string in characters. If you pass
  1675.         in NULL instead of the address of a variable
  1676.         no harm will be done.
  1677.  
  1678.     FullCheck - TRUE will cause the code to rattle through all
  1679.         possible slider settings, starting from the
  1680.         minimum value, ending at the maximum value.
  1681.         While this may be a good idea for a display
  1682.         function to map slider levels to text strings
  1683.         of varying length it might be a problem when
  1684.         it comes to display a range of numbers from
  1685.         1 to 40,000: the code will loop through
  1686.         40,000 iterations trying to find the longest
  1687.         string.
  1688.  
  1689.         FALSE will cause the code to calculate the
  1690.         longest level string based only on the
  1691.         minimum and the maximum value to check.
  1692.         While this is certainly a good a idea when
  1693.         it comes to display a range of numbers from
  1694.         1 to 40,000 as only two values will be
  1695.         checked the code may fail to produce
  1696.         accurate results for sliders using display
  1697.         functions mapping slider levels to strings.
  1698.  
  1699.    RESULT
  1700.     Index - The slider level which gives the longest
  1701.         level string.
  1702.  
  1703.    NOTES
  1704.     Some compilers have trouble passing parameters in A5. In such
  1705.     a case it is recommended to use gtlayout.library/LT_NewLevelWidth
  1706.     instead.
  1707.  
  1708.    SEE ALSO
  1709.     gtlayout.library/LT_NewLevelWidth
  1710.  
  1711. gtlayout.library/LT_LockWindow                 gtlayout.library/LT_LockWindow
  1712.  
  1713.    NAME
  1714.     LT_LockWindow -- Block user access to a window.
  1715.  
  1716.    SYNOPSIS
  1717.     LT_LockWindow(Window);
  1718.                     A0
  1719.  
  1720.     VOID LT_LockWindow(struct Window *);
  1721.  
  1722.    FUNCTION
  1723.     The window will get a wait mouse pointer attached and a blank
  1724.     Requester, preventing any user gadgets from getting used. The
  1725.     window minimum and maximum sizes are set to the current window
  1726.     size so the user will be unable to resize the window or click
  1727.     on the zoom gadget.
  1728.  
  1729.     This routine nests, multiple calls to LT_LockWindow() using the
  1730.     same window will increment a usage counter, so exactly the
  1731.     same number of calls to LT_UnlockWindow() will be required to
  1732.     unlock the window.
  1733.  
  1734.    INPUTS
  1735.     Window - Pointer to window structure; passign NULL is harmless.
  1736.  
  1737.    RESULT
  1738.     none
  1739.  
  1740.    NOTES
  1741.     Do not close the window you have locked unless all the
  1742.     outstanding locks are freed or memory will be lost which
  1743.     can never be reclaimed. Before you close the window,
  1744.     call gtlayout.library/LT_DeleteWindowLock.
  1745.  
  1746.    SEE ALSO
  1747.     gtlayout.library/LT_DeleteWindowLock
  1748.  
  1749. gtlayout.library/LT_MenuControlTagList gtlayout.library/LT_MenuControlTagList
  1750.  
  1751.    NAME
  1752.     LT_MenuControlTagList -- Manipulate menus, menu/submenu items (V11)
  1753.  
  1754.    SYNOPSIS
  1755.     LT_MenuControlTagList(Window,Menu,Tags)
  1756.                            A0   A1     A2
  1757.  
  1758.     VOID LT_MenuControlTagList(struct Window *,struct Menu *,struct TagItem *);
  1759.  
  1760.     VOID LT_MenuControlTags(struct Window *,struct Menu *,...);
  1761.  
  1762.    FUNCTION
  1763.     This routine provides a rather efficient way to set and to clear,
  1764.     to enable and to disable a number of menus, menu/submenu items
  1765.     all at once.
  1766.  
  1767.     In v18 this routine was modified to disconnect a menu strip
  1768.     from a window if it is about to change checkmark states. In
  1769.     earlier releases or if a single menu is attached to several
  1770.     windows it is recommended that you disconnect the menu from
  1771.     the windows it is attached to before you call this routine.
  1772.  
  1773.     As of v18 this routine is smart enough to handle menu
  1774.     mutual exclusion.
  1775.  
  1776.    INPUTS
  1777.     Window - Pointer to Window this menu is attached to. Starting with
  1778.              gtlayout.library v16 this parameter may be NULL.
  1779.  
  1780.     Menu - Pointer to Menu structure as returned by LT_NewMenuTagList.
  1781.  
  1782.     Tags - Pointer to a list of tagitem values, as found
  1783.            in gtlayout.h
  1784.  
  1785.  
  1786.     Tags:
  1787.  
  1788.     LAMN_ID (ULONG) - Unique ID of menu/menu item/submenu item to
  1789.         manipulate.
  1790.  
  1791.     LAMN_Checked (BOOL) - Set the checkmark state of the
  1792.         menu/submenu item.
  1793.  
  1794.     LAMN_Disabled (BOOL) - Set the availability state of the
  1795.         menu/menu item/submenu item.
  1796.  
  1797.     LAMN_FullMenuNum (UWORD) - Intuition menu number of
  1798.         menu/submenu item to manipulate. You would pass the
  1799.         result of the FULLMENUNUM() macro here for the
  1800.         item in question. (V30)
  1801.  
  1802.    RESULT
  1803.     none
  1804.  
  1805.    EXAMPLE
  1806.     The following tagitem list will clear the checkmark and
  1807.     disable the menu item associated with ID 5 and set the
  1808.     checkmark for the item associated with ID 6:
  1809.  
  1810.         LAMN_ID,         5,
  1811.           LAMN_Checked,  FALSE,
  1812.           LAMN_Disabled, TRUE,
  1813.         LAMN_ID,         6,
  1814.           LAMN_Checked,  TRUE,
  1815.         TAG_DONE
  1816.  
  1817.    BUGS
  1818.     In library versions up to and including v17.2 this routine
  1819.     is broken. It won't do any harm, it just doesn't do what you
  1820.     want it to do.
  1821.  
  1822.     Up to and including V42.1 the library could fail to find the
  1823.     correct menu items corresponding to the LAMN_ID given. This
  1824.     has been fixed in V43.1.
  1825.  
  1826.     Up to and including V43.1 trying to change the attributes
  1827.     of an item with LAMN_ID whose ID number could not be found
  1828.     could lead to a crash. This has been fixed in V43.2.
  1829.  
  1830.    SEE ALSO
  1831.     gtlayout.library/LT_NewMenuTagList
  1832.  
  1833. gtlayout.library/LT_NewA                             gtlayout.library/LT_NewA
  1834.  
  1835.    NAME
  1836.     LT_NewA -- Add a new object to the user interface tree.
  1837.  
  1838.    SYNOPSIS
  1839.     LT_NewA(Handle,Tags);
  1840.              A0    A1
  1841.  
  1842.     VOID LT_NewA(LayoutHandle *,struct TagItem *);
  1843.  
  1844.     LT_New(Handle,...);
  1845.  
  1846.     VOID LT_New(LayoutHandle *,...);
  1847.  
  1848.    FUNCTION
  1849.     LT_NewA() is the routine you use to build the user interface,
  1850.     you give layout directions, design groups, etc. and finally
  1851.     call LT_BuildA() to turn these specifications into a window.
  1852.  
  1853.    INPUTS
  1854.     Handle - Pointer to LayoutHandle structure.
  1855.  
  1856.  
  1857.     This routine will accept almost all create-time tag items
  1858.     gadtools.library/CreateGadget will handle. In addition to
  1859.     this there are a bunch of extra gadget objects and extra
  1860.     tag items supported:
  1861.  
  1862.     All object types:
  1863.  
  1864.         LA_Type (LONG) - Type of the object to create, must be
  1865.             one of the following:
  1866.  
  1867.                 TEXT_KIND
  1868.                 VERTICAL_KIND
  1869.                 HORIZONTAL_KIND
  1870.                 END_KIND
  1871.                 FRAME_KIND
  1872.                 BOX_KIND
  1873.                 SLIDER_KIND
  1874.                 LISTVIEW_KIND
  1875.                 INTEGER_KIND
  1876.                 STRING_KIND
  1877.                 PASSWORD_KIND
  1878.                 PALETTE_KIND
  1879.                 BUTTON_KIND
  1880.                 CHECKBOX_KIND
  1881.                 NUMBER_KIND
  1882.                 GAUGE_KIND
  1883.                 CYCLE_KIND
  1884.                 POPUP_KIND
  1885.                 TAB_KIND
  1886.                 MX_KIND
  1887.                 XBAR_KIND
  1888.                 YBAR_KIND
  1889.                 TAPEDECK_KIND
  1890.                 LEVEL_KIND
  1891.                 BOOPSI_KIND
  1892.                 BLANK_KIND (V36)
  1893.                 FRACTION_KIND (V38)
  1894.                 IMAGE_KIND (V41)
  1895.  
  1896.         LA_LabelText (STRPTR) - The object label text to use.
  1897.  
  1898.         LA_LabelID (LONG) - The locale text ID of the string to
  1899.             use as the object label text.
  1900.  
  1901.                 NOTE: LT_NewA() will fail if you forget
  1902.                     to select a hook with LAHN_LocaleHook
  1903.                     at LT_CreateHandleTagList.
  1904.  
  1905.         LA_ID (LONG) - The gadget ID to use for this object.
  1906.  
  1907.                 NOTE: User ID values *MUST* be greater than 0,
  1908.                       negative values are reserved for internal
  1909.                       use.
  1910.  
  1911.         LA_Chars (LONG) - The width of this object measured in
  1912.             characters. If each character of the user interface
  1913.             font is 8 pixels wide an object with LA_Chars set to
  1914.             10 will usually be 80 pixels wide.
  1915.  
  1916.         LA_LabelChars (LONG) - This forces the internal gadget
  1917.             label width the layout engine calculates during the
  1918.             layout pass to a specific value. Note: this does
  1919.             not work well with all objects. (V9)
  1920.  
  1921.         LA_LabelPlace (LONG) - Where to place the gadget label.
  1922.             Not all objects will support all label positions:
  1923.  
  1924.                 PLACE_LEFT - Place label text left of object
  1925.                 PLACE_RIGHT - Place label text right of object
  1926.                 PLACE_ABOVE - Place label text above object
  1927.                 PLACE_IN - Place label text in object
  1928.                 PLACE_BELOW - Place label text below object
  1929.  
  1930.         LA_ExtraSpace (BOOL) - Add extra vertical/horizontal
  1931.             space before this object.
  1932.             Default: FALSE
  1933.  
  1934.         LA_ExtraFat (BOOL) - Make this object a bit larger
  1935.             than its usual size.
  1936.             Default: FALSE
  1937.  
  1938.         LA_NoKey (BOOL) - Don't let the user interface choose
  1939.             a keyboard shortcut for this object.
  1940.             Default: FALSE
  1941.  
  1942.         LA_HighLabel (BOOL) - Use highlight pen when rendering
  1943.             the gadget label text.
  1944.             Default: FALSE
  1945.  
  1946.         LA_BYTE (BYTE *) - Pointer to the variable that holds
  1947.             the "current value" of the object. The layout engine
  1948.             will retrieve this value initially during the creation
  1949.             of the object and maintain it during its lifespan.
  1950.             This means you do not need to worry about checking
  1951.             the state of the object, the user interface layout
  1952.             engine will do it for you.
  1953.  
  1954.         LA_UBYTE (UBYTE *) - Pointer to the variable that holds
  1955.             the "current value" of the object. The layout engine
  1956.             will retrieve this value initially during the creation
  1957.             of the object and maintain it during its lifespan.
  1958.             This means you do not need to worry about checking
  1959.             the state of the object, the user interface layout
  1960.             engine will do it for you.
  1961.  
  1962.         LA_WORD (WORD *) - Pointer to the variable that holds
  1963.             the "current value" of the object. The layout engine
  1964.             will retrieve this value initially during the creation
  1965.             of the object and maintain it during its lifespan.
  1966.             This means you do not need to worry about checking
  1967.             the state of the object, the user interface layout
  1968.             engine will do it for you.
  1969.  
  1970.         LA_UWORD (UWORD *) - Pointer to the variable that holds
  1971.             the "current value" of the object. The layout engine
  1972.             will retrieve this value initially during the creation
  1973.             of the object and maintain it during its lifespan.
  1974.             This means you do not need to worry about checking
  1975.             the state of the object, the user interface layout
  1976.             engine will do it for you.
  1977.  
  1978.         LA_BOOL (BOOL *) - Pointer to the variable that holds
  1979.             the "current value" of the object. The layout engine
  1980.             will retrieve this value initially during the creation
  1981.             of the object and maintain it during its lifespan.
  1982.             This means you do not need to worry about checking
  1983.             the state of the object, the user interface layout
  1984.             engine will do it for you.
  1985.  
  1986.         LA_LONG (LONG *) - Pointer to the variable that holds
  1987.             the "current value" of the object. The layout engine
  1988.             will retrieve this value initially during the creation
  1989.             of the object and maintain it during its lifespan.
  1990.             This means you do not need to worry about checking
  1991.             the state of the object, the user interface layout
  1992.             engine will do it for you.
  1993.  
  1994.         LA_ULONG (ULONG *) - Pointer to the variable that holds
  1995.             the "current value" of the object. The layout engine
  1996.             will retrieve this value initially during the creation
  1997.             of the object and maintain it during its lifespan.
  1998.             This means you do not need to worry about checking
  1999.             the state of the object, the user interface layout
  2000.             engine will do it for you.
  2001.  
  2002.         LA_STRPTR (STRPTR) - Pointer to the variable that holds
  2003.             the "current value" of the object. The layout engine
  2004.             will retrieve this value initially during the creation
  2005.             of the object and maintain it during its lifespan.
  2006.             This means you do not need to worry about checking
  2007.             the state of the object, the user interface layout
  2008.             engine will do it for you.
  2009.  
  2010.         LA_FRACTION (FRACTION *) - Pointer to the variable that holds
  2011.             the "current value" of the object. The layout engine
  2012.             will retrieve this value initially during the creation
  2013.             of the object and maintain it during its lifespan.
  2014.             This means you do not need to worry about checking
  2015.             the state of the object, the user interface layout
  2016.             engine will do it for you.
  2017.  
  2018.  
  2019.         BLANK_KIND (transparent placeholder):
  2020.  
  2021.             (requires gtlayout.library V36 or higher)
  2022.  
  2023.             No tags are defined for this type of object.
  2024.  
  2025.  
  2026.         BOOPSI_KIND:
  2027.  
  2028.             (requires gtlayout.library V10 or higher)
  2029.  
  2030.             LABO_TagCurrent (Tag) - The Tag ID that represents the
  2031.                 current object value. For PROPGCLASS this would be
  2032.                 PGA_Top.
  2033.  
  2034.             LABO_TagTextAttr (Tag) - The Tag ID that represents the
  2035.                 TextAttr value the object expects. For gadgets this
  2036.                 would be GA_TextAttr.
  2037.  
  2038.             LABO_TagDrawInfo (Tag) - The Tag ID that represents the
  2039.                 DrawInfo value the object expects.
  2040.  
  2041.             LABO_TagLink (Tag) - The Tag ID that represents a pointer
  2042.                 to a different object the object expects. For the
  2043.                 colorwheel.gadget this would be WHEEL_GradientSlider.
  2044.  
  2045.             LABO_TagScreen (Tag) - The Tag ID that represents the
  2046.                 screen the object expects. For the colorwheel.gadget
  2047.                 this would be WHEEL_Screen.
  2048.  
  2049.             LABO_Link (LONG) - The ID of the object this object should
  2050.                 be linked to. This will be resolved later when gadgets
  2051.                 are created.
  2052.  
  2053.                     NOTE: Forward references are not resolved, only
  2054.                         backward references are allowed. This means that
  2055.                         if you wish to link object A to object B,
  2056.                         object A must be created before object B
  2057.                         is created.
  2058.  
  2059.             LABO_ClassInstance (Class *) - This is the first parameter
  2060.                 you would pass to NewObjectA().
  2061.  
  2062.                     NOTE: Only classes derived from gadgetclass and
  2063.                       gadgetclass itself may be used.
  2064.  
  2065.             LABO_ClassName (STRPTR) - This is the second parameter you would
  2066.                 pass to NewObject().
  2067.  
  2068.                     NOTE: Only classes derived from gadgetclass and
  2069.                         gadgetclass itself may be used.
  2070.  
  2071.             LABO_ClassLibraryName (STRPTR) - This tag is particularly useful
  2072.                 for gadget class implementations wrapped into libraries, such as
  2073.                 colorwheel.gadget. When opened, they make the classes they
  2074.                 represent publicly available so subsequent calls to
  2075.                 NewObject(NULL,<Classname>,...) can be made. The
  2076.                 LABO_ClassLibraryName tag will cause gtlayout.library to open
  2077.                 the class library before any calls to NewObject() are made.
  2078.  
  2079.                     NOTE: Only classes derived from gadgetclass and
  2080.                         gadgetclass itself may be used.
  2081.  
  2082.                         The LABO_ClassLibraryName tag requires that you
  2083.                         specify the class name with the LABO_ClassName. It is
  2084.                         not enough to just use the LABO_ClassLibraryName tag.
  2085.  
  2086.             LABO_ExactWidth (WORD) - This is the exact width of the object to
  2087.                 use. This effectively overrides whatever you specified using
  2088.                 the LA_Chars tag and keeps gtlayout.library from shrinking and
  2089.                 expanding the object as needed.
  2090.  
  2091.             LABO_ExactHeight (WORD) - This is the exact height of the object to
  2092.                 use. This effectively overrides whatever you specified using
  2093.                 the LA_Lines tag and keeps gtlayout.library from shrinking and
  2094.                 expanding the object as needed.
  2095.  
  2096.             LABO_RelFontHeight (WORD) - This tag affects the height of the
  2097.                 object; when specified, it is derived from the user interface
  2098.                 font height plus the value given with LABO_RelFontHeight.
  2099.  
  2100.             LABO_FullWidth (BOOL) - Use this tag if you wish the object to
  2101.                 cover the entire width of the group it resides within.
  2102.  
  2103.             LABO_FullHeight (BOOL) - Use this tag if you wish the object to
  2104.                 cover the entire height of the group it resides within.
  2105.  
  2106.             LABO_ActivateHook (struct Hook *) - Hook to invoke when the
  2107.                 layout engine decides that this particular object should
  2108.                 be activated. The hook is called with the following
  2109.                 parameters:
  2110.  
  2111.                 Success = ActivateFunc(struct Hook *Hook,LayoutHandle *Handle,
  2112.                   D0                                 A0                  A2
  2113.  
  2114.                              Object *object)
  2115.                                        A1
  2116.  
  2117.                 The object pointer actually refers to the instance of the
  2118.                 BOOPSI object created. Return FALSE if your object could not
  2119.                 be activated, TRUE if it worked. If you return TRUE, no special
  2120.                 keyboard event will be generated. (V13)
  2121.  
  2122.             NOTE: All tags passed to LT_New() for BOOPSI_KIND objects are
  2123.                 passed through to NewObjectA() later. The library makes
  2124.                 a copy of the tag item list, so all data valid in the
  2125.                 scope when LT_New() is called must also be valid later
  2126.                 when LT_Build() is invoked.
  2127.  
  2128.                 The gadget label is *NOT* passed through to the object,
  2129.                 it effectively receives the label a plain gadtools object
  2130.                 would receive, similar to what happens to FRAME_KIND
  2131.                 objects and the like.
  2132.  
  2133.  
  2134.         BOX_KIND (multiline text display):
  2135.  
  2136.             LABX_Chars (LONG) - The width of this object in
  2137.                 characters. The layout routine will try to make
  2138.                 sure that the given number of characters will
  2139.                 fit into a single line of text in this box.
  2140.                 This may be a problem with proportional spaced
  2141.                 fonts.
  2142.                Default: 10
  2143.  
  2144.             LABX_Labels (STRPTR *) - The label texts to display
  2145.                 on the right hand side of the box. Terminate
  2146.                 this array with NULL.
  2147.  
  2148.             LABX_Lines (STRPTR *) - The text to display in the
  2149.                 box. Terminate this array with NULL.
  2150.  
  2151.             LABX_Rows (LONG) - The height of this object in
  2152.                 characters.
  2153.  
  2154.             LABX_AlignText (LONG) - Controls how text is aligned
  2155.                 in box lines:
  2156.  
  2157.                     ALIGNTEXT_LEFT - Align text to the left edge
  2158.                     ALIGNTEXT_CENTERED - Centre the text
  2159.                     ALIGNTEXT_RIGHT - Align text to the right edge
  2160.                     ALIGNTEXT_PAD - Pad text lines
  2161.  
  2162.                 Default: ALIGNTEXT_LEFT
  2163.  
  2164.             LABX_DrawBox (BOOL) - Draw a recessed bevel box
  2165.                 around the text box.
  2166.                 Default: FALSE
  2167.  
  2168.             LABX_FirstLabel (LONG) - Locale string ID of the first
  2169.                 text to use as a box label. Works in conjunction
  2170.                 with LABX_LastLabel.
  2171.  
  2172.             LABX_LastLabel (LONG) - Locale string ID of the last
  2173.                 text to use as a box label. Works in conjunction
  2174.                 with LABX_FirstLabel. When building the interface the
  2175.                 code will loop from FirstLabel..LastLabel, look
  2176.                 up the corresponding locale strings and use the
  2177.                 data to make up the label text to appear at the
  2178.                 right hand side of the box.
  2179.  
  2180.             LABX_LabelTable (LONG *) - Pointer to an array of IDs
  2181.                 to use for building the box labels. This requires
  2182.                 that a locale hook is provided with the layout handle.
  2183.                 The array is terminated by -1.
  2184.  
  2185.             LABX_ReserveSpace (BOOL) - Allocate extra memory to hold
  2186.                 the contents of the lines displayed. This avoids nasty
  2187.                 side-effects when refreshing this object.
  2188.                 Default: FALSE
  2189.  
  2190.             LABX_FirstLine (LONG) - Locale string ID of the first
  2191.                 text to print inside the box. Works in conjunction
  2192.                 with LABX_LastLine. (V26)
  2193.  
  2194.             LABX_LastLine (LONG) - Locale string ID of the last
  2195.                 text to print inside the box. Works in conjunction
  2196.                 with LABX_FirstLine. (V26)
  2197.  
  2198.             LABX_LineTable (LONG *) - Pointer to an array of IDs
  2199.                 to use for building the box contents lines. This requires
  2200.                 that a locale hook is provided with the layout handle.
  2201.                 The array is terminated by -1. (V28)
  2202.  
  2203.             LABX_Line (STRPTR) - Line to display in the box, may
  2204.                 contain '\n' line break characters, the layout engine
  2205.                 will chop the single line into single consecutive lines
  2206.                 following the '\n' chars. (V31)
  2207.  
  2208.             LABX_LineID (LONG) - Locale ID of line text to display in the
  2209.                 box, may contain '\n' line break characters, the layout
  2210.                 engine will chop the single line into single consecutive lines
  2211.                 following the '\n' chars. (V31)
  2212.  
  2213.             LABX_TextPen (WORD) - Box text colour to use. (V40)
  2214.  
  2215.             LABX_BackPen (WORD) - Box text background colour to use. (V40)
  2216.  
  2217.             LABX_Spacing (UWORD) - Request that additional pixels should
  2218.                 separate lines of text. (V41)
  2219.                 Default: 0
  2220.  
  2221.  
  2222.         BUTTON_KIND:
  2223.  
  2224.             LA_Label (STRPTR)
  2225.             LA_LabelID (LONG) - These two define the button label, i.e.
  2226.                 the text that is printed within the button box. Optionally,
  2227.                 this text may include newline characters ("\n") which will
  2228.                 cause the button text to be broken into several lines.
  2229.                 This particular feature requires gtlayout.library v12 or
  2230.                 higher. Single line label have always been supported.
  2231.  
  2232.             LABT_ReturnKey (BOOL) - Let the user operate this
  2233.                 button by pressing the return key, making it the
  2234.                 so-called default button, or default choice. The
  2235.                 button select box will appear slightly bolder than
  2236.                 normal buttons are.
  2237.  
  2238.                     NOTE: there can be only one single button per
  2239.                         window to sport this feature.
  2240.  
  2241.                 Default: FALSE
  2242.  
  2243.             LABT_EscKey (BOOL) - Let the user operate this
  2244.                 button by pressing the Escape key.
  2245.  
  2246.                     NOTE: there can be only one single button per
  2247.                         window to use this feature.
  2248.  
  2249.                 Default: FALSE
  2250.  
  2251.             LABT_ExtraFat (BOOL) - Make this button a bit
  2252.                 larger than usual.
  2253.                 Default: FALSE
  2254.  
  2255.             LABT_Lines (STRPTR *) - Use the given string array
  2256.                 to create a multiline gadget label. Terminate the
  2257.                 array with a NULL. (V12)
  2258.  
  2259.             LABT_FirstLine (LONG) - Locale ID of first label line. (V12)
  2260.  
  2261.             LABT_LastLine (LONG) - Locale ID of last label line. (V12)
  2262.  
  2263.             LABT_DefaultCorrection (BOOL) - Make the button slightly
  2264.                 wider and taller so its size matches the default
  2265.                 button. (V21)
  2266.  
  2267.             LABT_Smaller (BOOL) - Make this button a little smaller
  2268.                 than usual. (V21)
  2269.  
  2270.  
  2271.         CYCLE_KIND:
  2272.  
  2273.             LACY_FirstLabel (LONG) - Locale string ID of the first
  2274.                 text to use as a label. Works in conjunction
  2275.                 with LACY_LastLabel.
  2276.  
  2277.             LACY_LastLabel (LONG) - Locale string ID of the last
  2278.                 text to use as a label. Works in conjunction
  2279.                 with LACY_FirstLabel. When building the interface the
  2280.                 code will loop from FirstLabel..LastLabel, look
  2281.                 up the corresponding locale strings and use the
  2282.                 data to make up the label text.
  2283.  
  2284.             LACY_LabelTable (LONG *) - Pointer to an array of IDs
  2285.                 to use for building the cycle labels. This requires
  2286.                 that a locale hook is provided with the layout handle.
  2287.                 The array is terminated by -1.
  2288.  
  2289.             LACY_TabKey (BOOL) - Connect this object to the tabulator
  2290.                 key. Press [Tab] to cycle to the next entry, [Shift][Tab]
  2291.                 to cycle to the previous entry. (V9)
  2292.  
  2293.                     NOTE: there can be only one single button per
  2294.                         window to use this feature.
  2295.  
  2296.                 Default: FALSE
  2297.  
  2298.             LACY_AutoPageID (LONG) - ID of paged GROUP_KIND object
  2299.                 which will be set to the gadget's current setting.
  2300.                 If this tag is set, you will hear no events from this
  2301.                 object any more. (V7)
  2302.  
  2303.                     NOTE: Listen to IDCMP_CLOSEWINDOW events
  2304.                         which may be generated if the layout
  2305.                         engine runs out of memory when rebuilding
  2306.                         the user interface.
  2307.  
  2308.  
  2309.         FRACTION_KIND:
  2310.  
  2311.             (requires gtlayout.library V38 or higher)
  2312.  
  2313.             This is a special kind of STRING_KIND which comes with a
  2314.             special input filter. It will allow only for floating point
  2315.             numbers to be entered, i.e. numbers (`0'-`9') and one
  2316.             decimal point (`.' or whatever your current locale uses
  2317.             as the decimal point character). What you will receive as
  2318.             user input text will be in the following format:
  2319.  
  2320.                 (0|#[0-9]).(0|#[0-9])
  2321.  
  2322.             Or in other words, text like this will be returned:
  2323.  
  2324.                 0.0
  2325.                 7.0
  2326.                 0.9
  2327.                 146654.0
  2328.  
  2329.             NOTE: While this object type did exist in earlier library
  2330.                   versions support for it was removed in V33. It was
  2331.                   eventually reintroduced with the functionality described
  2332.                   above in V38.
  2333.  
  2334.             LAFR_IncrementerHook (struct Hook *) - Hook to invoke when the
  2335.                 incrementer arrows are used. The hook function will receive
  2336.                 three parameters and has to return a result code:
  2337.  
  2338.                     a0 - (struct Hook *)  Pointer to this hook
  2339.                     a2 - (STRPTR) Current value of this object
  2340.                     a1 - (LONG) Either INCREMENTERMSG_Decrement or
  2341.                                 INCREMENTERMSG_Increment
  2342.  
  2343.                 If the hook function modifies the current value it must
  2344.                 return TRUE, otherwise FALSE must be returned. If you return
  2345.                 TRUE, then the library will update the object. (V40)
  2346.  
  2347.             This object type accepts all the GTST_#? tag items.
  2348.  
  2349.  
  2350.         FRAME_KIND (fixed size general purpose display,
  2351.             you may render into it):
  2352.  
  2353.             LAFR_InnerWidth (LONG) - Inner width of the
  2354.                 display box.
  2355.  
  2356.             LAFR_InnerHeight (LONG) - Inner height of the
  2357.                 display box.
  2358.  
  2359.             LAFR_DrawBox (BOOL) - Draw a recessed bevel box
  2360.                 around the display box.
  2361.                 Default: FALSE
  2362.  
  2363.             LAFR_RefreshHook (struct Hook *) - Hook to call
  2364.                 when refreshing/redrawing this object. See
  2365.                 gtlayout.h for more information. (V9)
  2366.  
  2367.             LAFR_GenerateEvents (BOOL) - If TRUE, clicking
  2368.                 inside the FRAME_KIND object will generate
  2369.                 IDCMP_GADGETUP/IDCMP_GADGETDOWN events. If
  2370.                 you wish to know where the click occured,
  2371.                 make a copy of the Window->MouseX/Y entries
  2372.                 before you call LT_HandleInput()/LT_GetIMsg(). (V28)
  2373.                 Default: FALSE
  2374.  
  2375.             LAFR_ResizeX (BOOL) - Makes this frame resizable
  2376.                 in the horizontal direction, attaches a sizing
  2377.                 gadget to the window to open and handles window
  2378.                 resize operations automatically. (V44)
  2379.  
  2380.                     NOTE: there can be only one single object
  2381.                         per window to sport this feature. This
  2382.                         means that you won't be able to have
  2383.                         both a resizable listview and a resizable
  2384.                         frame in the same window.
  2385.  
  2386.                         Also listen to IDCMP_CLOSEWINDOW events
  2387.                         which may be generated if the layout
  2388.                         engine runs out of memory when rebuilding
  2389.                         the user interface.
  2390.  
  2391.                 Default: FALSE
  2392.  
  2393.             LAFR_ResizeY (BOOL) - Makes this frame resizable
  2394.                 in the vertical direction, attaches a sizing
  2395.                 gadget to the window to open and handles window
  2396.                 resize operations automatically. (V44)
  2397.  
  2398.                     NOTE: there can be only one single object
  2399.                         per window to sport this feature. This
  2400.                         means that you won't be able to have
  2401.                         both a resizable listview and a resizable
  2402.                         frame in the same window.
  2403.  
  2404.                         Also listen to IDCMP_CLOSEWINDOW events
  2405.                         which may be generated if the layout
  2406.                         engine runs out of memory when rebuilding
  2407.                         the user interface.
  2408.  
  2409.                 Default: FALSE
  2410.  
  2411.         GAUGE_KIND (general purpose progress report display):
  2412.  
  2413.             LAGA_Percent (LONG) - Indicator position, can range
  2414.                 from 0..100.
  2415.                 Default: 0
  2416.  
  2417.             LAGA_InfoLength (LONG) - Maximum number of characters
  2418.                 to reserve for text printed in the gauge display.
  2419.                 Default: 0
  2420.  
  2421.             LAGA_InfoText (STRPTR) - Text to print in the gauge
  2422.                 display.
  2423.  
  2424.             LAGA_Tenth (BOOL) - Instead of a continuously growing
  2425.                 bar you will get a set of exactly ten blocks,
  2426.                 each separated by a hairline. (V19)
  2427.                 Default: FALSE
  2428.  
  2429.                LAGA_NoTicks (BOOL) - If TRUE suppresses drawing the
  2430.                    ticks below the gauge box.
  2431.                    Default: FALSE
  2432.  
  2433.  
  2434.         IMAGE_KIND (display area for Image or BitMap data):
  2435.  
  2436.             (requires gtlayout.library V41 or higher)
  2437.  
  2438.             LAIM_Image (struct Image *) - Image to draw in this
  2439.                 place. When the user interface is built, it will
  2440.                 be drawn using intuition.library/DrawImage().
  2441.  
  2442.             LAIM_BitMap (struct BitMap *) - You can supply a
  2443.                 BitMap instead of an Image which will be drawn
  2444.                 using either graphics.library/BltBitMapRastPort()
  2445.                 or graphics.library/BltMaskBitMapRastPort() if
  2446.                 a mask is provided.
  2447.  
  2448.             LAIM_BitMapLeft (UWORD) - Left corner of the image data
  2449.                 to blit into the window (the second parameter for
  2450.                 BltBitMapRastPort()).
  2451.  
  2452.             LAIM_BitMapTop (UWORD) - Top corner of the image data
  2453.                 to blit into the window (the third parameter for
  2454.                 BltBitMapRastPort()).
  2455.  
  2456.             LAIM_BitMapWidth (UWORD) - Width of the bitmap area to
  2457.                 blit into the window.
  2458.  
  2459.             LAIM_BitMapHeight (UWORD) - Height of the bitmap area to
  2460.                 blit into the window.
  2461.  
  2462.             LAIM_BitMapMask (PLANEPTR) - Pointer to a bit plane mask
  2463.                 to blit the image bitmap through. Must follow the
  2464.                 rules documented for for BltMaskBitMapRastPort().
  2465.                 The blit operation will use the minterm for
  2466.                 transparency.
  2467.  
  2468.  
  2469.         INTEGER_KIND:
  2470.  
  2471.             LAIN_LastGadget (BOOL) - Pressing return with this
  2472.                 gadget active will stop activating the next
  2473.                 following string gadget type if TRUE is passed.
  2474.                 Default: FALSE
  2475.  
  2476.             LAIN_Min (LONG) - Minimum accepted numeric value.
  2477.                 Default: -2147483647
  2478.  
  2479.             LAIN_Max (LONG) - Maximum accepted numeric value.
  2480.                 Default:  2147483647
  2481.  
  2482.             LAIN_UseIncrementers (BOOL) - Use TRUE to add incrementer
  2483.                 arrow buttons to the right of the numeric entry field.
  2484.                 These buttons will let you cycle through a set of
  2485.                 numbers to be displayed in the numeric entry field.
  2486.                 Default: FALSE
  2487.  
  2488.             LAIN_HistoryLines (LONG) - Number of numbers entered to
  2489.                 keep as a backlog.
  2490.                 Default: 0
  2491.  
  2492.             LAIN_HistoryHook (struct Hook *) - Hook code to call when
  2493.                 entering a number into the backlog. See gtlayout.h for
  2494.                 more information.
  2495.                 Default: NULL
  2496.  
  2497.             LAIN_IncrementerHook (struct Hook *) - Hook code to call
  2498.                 when cycling through numeric values. See gtlayout.h for
  2499.                 more information.
  2500.                 Default: NULL
  2501.  
  2502.             LAIN_Activate (BOOL) - When the window opens, make this
  2503.                 gadget the active one. (V21)
  2504.  
  2505.                     NOTE: There can be only one gadget of this type
  2506.                         per window.
  2507.  
  2508.                 Default: FALSE
  2509.  
  2510.  
  2511.         LEVEL_KIND:
  2512.  
  2513.             All tags are supported which SLIDER_KIND supports.
  2514.             The gadget level display however, can only be aligned
  2515.             to the left border.
  2516.  
  2517.             LAVL_Freedom (WORD) - Selects the orientation of the
  2518.                 slider body; can be either FREEHORIZ or FREEVERT. (V41)
  2519.  
  2520.                 Default: FREEHORIZ
  2521.  
  2522.             LAVL_Ticks (WORD) - Selects if and where to place tick
  2523.                 marks next to the slider body. Can be one of the
  2524.                 the following: TICKS_None (no ticks), TICKS_Left
  2525.                 (place ticks left of the body), TICKS_Above (place
  2526.                 ticks above the body), TICKS_Both (place ticks on
  2527.                 both sides of the body). (V41)
  2528.  
  2529.                 Default: TICKS_None
  2530.  
  2531.             LAVL_NumTicks (LONG) - Number of tick marks to draw. (V41)
  2532.  
  2533.             LAVL_Lines (LONG) - Height of the slider, if FREEVERT. (V41)
  2534.  
  2535.  
  2536.         LISTVIEW_KIND:
  2537.  
  2538.             LALV_ExtraLabels (STRPTR *) - Place extra line
  2539.                 labels at the right of the box. Terminate
  2540.                 this array with NULL.
  2541.  
  2542.             LALV_Labels (STRPTR *) - The labels to display
  2543.                 inside the box, you can pass this array of
  2544.                 strings in rather than passing an initialized
  2545.                 List of text via GTLV_Labels. Terminate
  2546.                 this array with NULL.
  2547.  
  2548.             LALV_CursorKey (BOOL) - Let the user operate this
  2549.                 listview using the cursor keys.
  2550.  
  2551.                     NOTE: there can be only one single listview
  2552.                         per window to sport this feature.
  2553.  
  2554.                 Default: FALSE
  2555.  
  2556.             LALV_Lines (LONG) - The number of text lines this
  2557.                 listview is to display.
  2558.  
  2559.             LALV_Link (LONG) - The Gadget ID of a string gadget
  2560.                 to attach to this listview.
  2561.  
  2562.                     NOTE: you need to
  2563.                         add the Gadget in question before you add the
  2564.                         listview to refer to it or the layout routine
  2565.                         will get confused.
  2566.  
  2567.                 Passing the value NIL_LINK will create a listview
  2568.                 which displays the currently selected item, otherwise
  2569.                 you will get a read-only list.
  2570.  
  2571.             LALV_FirstLabel (LONG) - Locale string ID of the first
  2572.                 text to use as a list label. Works in conjunction
  2573.                 with LALV_LastLabel.
  2574.  
  2575.             LALV_LastLabel (LONG) - Locale string ID of the last
  2576.                 text to use as a list label. Works in conjunction
  2577.                 with LALV_FirstLabel. When building the interface the
  2578.                 code will loop from FirstLabel..LastLabel, look
  2579.                 up the corresponding locale strings and use the
  2580.                 data to make up the label text to appear in the
  2581.                 list.
  2582.  
  2583.             LALV_LabelTable (LONG *) - Pointer to an array of IDs
  2584.                 to use for building the listview contents. This requires
  2585.                 that a locale hook is provided with the layout handle.
  2586.                 The array is terminated by -1.
  2587.  
  2588.             LALV_MaxGrowX (LONG) - Maximum width of this object
  2589.                 measured in characters. When the first layout pass
  2590.                 is finished and there is still enough space left
  2591.                 to make the listview wider, the width is increased
  2592.                 until it hits the limit specified using this tag.
  2593.  
  2594.                     NOTE: there can be only one single listview
  2595.                         per window to sport this feature.
  2596.  
  2597.                 Default: 0
  2598.  
  2599.             LALV_MaxGrowY (LONG) - Maximum height of this object
  2600.                 measured in lines. When the first layout pass is
  2601.                 finished and there is still enough space left to
  2602.                 make the listview higher, the height is increased
  2603.                 until it hits the limit specified using this tag.
  2604.  
  2605.                     NOTE: there can be only one single listview
  2606.                         per window to sport this feature.
  2607.  
  2608.                 Default: 0
  2609.  
  2610.             LALV_ResizeX (BOOL) - Makes this listview resizable
  2611.                 in the horizontal direction, attaches a sizing
  2612.                 gadget to the window to open and handles window
  2613.                 resize operations automatically. (V9)
  2614.  
  2615.                     NOTE: there can be only one single object
  2616.                         per window to sport this feature. This
  2617.                         means that you won't be able to have
  2618.                         both a resizable listview and a resizable
  2619.                         frame in the same window.
  2620.  
  2621.                         Also listen to IDCMP_CLOSEWINDOW events
  2622.                         which may be generated if the layout
  2623.                         engine runs out of memory when rebuilding
  2624.                         the user interface.
  2625.  
  2626.                 Default: FALSE
  2627.  
  2628.             LALV_ResizeY (BOOL) - Makes this listview resizable
  2629.                 in the vertical direction, attaches a sizing
  2630.                 gadget to the window to open and handles window
  2631.                 resize operations automatically. (V9)
  2632.  
  2633.                     NOTE: there can be only one single object
  2634.                         per window to sport this feature. This
  2635.                         means that you won't be able to have
  2636.                         both a resizable listview and a resizable
  2637.                         frame in the same window.
  2638.  
  2639.                         Also listen to IDCMP_CLOSEWINDOW events
  2640.                         which may be generated if the layout
  2641.                         engine runs out of memory when rebuilding
  2642.                         the user interface.
  2643.  
  2644.                 Default: FALSE
  2645.  
  2646.             LALV_MinChars (WORD) - Minimum width for this
  2647.                 object, measured in characters. Used in
  2648.                 conjunction with LALV_ResizeX. (V9)
  2649.  
  2650.             LALV_MinLines (WORD) - Minimum height for this
  2651.                 object, measured in lines. Used in
  2652.                 conjunction with LALV_ResizeY. (V9)
  2653.  
  2654.             LALV_LockSize (BOOL) - After doing the initial layout
  2655.                 for this object, do not adapt its size again during
  2656.                 subsequent layouts. This is particularly useful if
  2657.                 you have a LISTVIEW_KIND object in a paged group
  2658.                 and keep adding new entries to the list. You need
  2659.                 to specify an object width using LA_Chars, otherwise
  2660.                 the layout engine may make it not wide enough to
  2661.                 display any entries. (V8)
  2662.  
  2663.             LALV_FlushLabelLeft (BOOL) - For a gadget label placed
  2664.                 above the listview align the text to the left edge
  2665.                 of the view. (V9)
  2666.  
  2667.             LALV_TextAttr (struct TextAttr *) - You can specify a
  2668.                 fixed-width font to be used for the list display.
  2669.                 The TextAttr (or TTextAttr) you provide must be ready
  2670.                 to go so the layout code can open the font later.
  2671.  
  2672.                 To get the current system default font, which is
  2673.                 guaranteed to be fixed-width, pass ~0 instead of a
  2674.                 pointer to a TextAttr structure. (V10)
  2675.  
  2676.                     NOTE: The font *MUST* be fixed-width or the layout
  2677.                         will fail.
  2678.  
  2679.                          Choose your font in such a way that it matches
  2680.                          in width and height with the other probably
  2681.                          proportional-spaced user interface font.
  2682.  
  2683.                          If the layout engine decides to step down in
  2684.                          font size, all LISTVIEW_KIND objects which were
  2685.                          configured to use a special fixed-width font
  2686.                          will `forget' about it. This won't matter much
  2687.                          as the fonts the engine chooses will always be
  2688.                          fixed-width anyway.
  2689.  
  2690.             LALV_AutoPageID (LONG) - ID of paged GROUP_KIND object
  2691.                 which will be set to the gadget's current setting.
  2692.                 If this tag is set, you will hear no events from this
  2693.                 object any more. (V23)
  2694.  
  2695.                     NOTE: Listen to IDCMP_CLOSEWINDOW events
  2696.                         which may be generated if the layout
  2697.                         engine runs out of memory when rebuilding
  2698.                         the user interface.
  2699.  
  2700.             LALV_Selected (LONG) - In this context, this tag is an
  2701.                 alias for GTLV_Selected. See
  2702.                 gtlayout.library/LT_SetAttributes for more information
  2703.                 on how the meaning of this tag differs from this (V34).
  2704.  
  2705.  
  2706.         MX_KIND:
  2707.  
  2708.             LAMX_FirstLabel (LONG) - Locale string ID of the first
  2709.                 text to use as a label. Works in conjunction
  2710.                 with LAMX_LastLabel.
  2711.  
  2712.             LAMX_LastLabel (LONG) - Locale string ID of the last
  2713.                 text to use as a label. Works in conjunction
  2714.                 with LAMX_FirstLabel. When building the interface the
  2715.                 code will loop from FirstLabel..LastLabel, look
  2716.                 up the corresponding locale strings and use the
  2717.                 data to make up the label text.
  2718.  
  2719.             LAMX_LabelTable (LONG *) - Pointer to an array of IDs
  2720.                 to use for building the radio labels. This requires
  2721.                 that a locale hook is provided with the layout handle.
  2722.                 The array is terminated by -1.
  2723.  
  2724.             LAMX_TabKey (BOOL) - Connect this object to the tabulator
  2725.                 key. Press [Tab] to cycle to the next entry, [Shift][Tab]
  2726.                 to cycle to the previous entry. (V9)
  2727.  
  2728.                     NOTE: there can be only one single button per
  2729.                         window to use this feature.
  2730.  
  2731.                 Default: FALSE
  2732.  
  2733.             LAMX_AutoPageID (LONG) - ID of paged GROUP_KIND object
  2734.                 which will be set to the gadget's current setting.
  2735.                 If this tag is set, you will hear no events from this
  2736.                 object any more. (V7)
  2737.  
  2738.                     NOTE: Listen to IDCMP_CLOSEWINDOW events
  2739.                         which may be generated if the layout
  2740.                         engine runs out of memory when rebuilding
  2741.                         the user interface.
  2742.  
  2743.  
  2744.         PALETTE_KIND:
  2745.  
  2746.             LAPA_SmallPalette (BOOL) - Make the palette display
  2747.                 a bit smaller than usual.
  2748.                 Default: FALSE
  2749.  
  2750.             LAPA_Lines (LONG) - Number of lines the palette
  2751.                 display should cover.
  2752.                 Default: No preference
  2753.  
  2754.             LAPA_UsePicker (BOOL) - This tag effectively changes the
  2755.                 gadget type. Instead of a list of colours to pick from
  2756.                 the user will see a rectangle filled in the selected
  2757.                 colour with a picker button next to it. This gadget
  2758.                 will generate IDCMP_IDCMPUPDATE events when the picker
  2759.                 button is pressed. (V10)
  2760.  
  2761.  
  2762.         PASSWORD_KIND (string gadget type which does not
  2763.             display its contents):
  2764.  
  2765.             LAPW_LastGadget (BOOL) - Pressing return with this
  2766.                 gadget active will stop activating the next
  2767.                 following string gadget type if TRUE is passed.
  2768.                 Default: FALSE
  2769.  
  2770.             LAPW_HistoryLines (LONG) - Number of lines to keep as
  2771.                 a backlog.
  2772.                 Default: 0
  2773.  
  2774.             LAPW_HistoryHook (struct Hook *) - Hook code to call
  2775.                 when entering a line into the backlog. See gtlayout.h
  2776.                 for more information.
  2777.                 Default: NULL
  2778.  
  2779.             LAPW_Activate (BOOL) - When the window opens, make this
  2780.                 gadget the active one. (V21)
  2781.  
  2782.                     NOTE: There can be only one gadget of this type
  2783.                         per window.
  2784.  
  2785.                 Default: FALSE
  2786.  
  2787.             This object type accepts all the GTST_#? tag items.
  2788.  
  2789.  
  2790.         POPUP_KIND:
  2791.  
  2792.             (This features requires gtlayout.library v22 or higher
  2793.              and Kickstart 3.0 or higher).
  2794.  
  2795.             LAPU_FirstLabel (LONG) - Locale string ID of the first
  2796.                 text to use as a label. Works in conjunction
  2797.                 with LAPU_LastLabel.
  2798.  
  2799.             LAPU_LastLabel (LONG) - Locale string ID of the last
  2800.                 text to use as a label. Works in conjunction
  2801.                 with LAPU_FirstLabel. When building the interface the
  2802.                 code will loop from FirstLabel..LastLabel, look
  2803.                 up the corresponding locale strings and use the
  2804.                 data to make up the label text.
  2805.  
  2806.             LAPU_LabelTable (LONG *) - Pointer to an array of IDs
  2807.                 to use for building the cycle labels. This requires
  2808.                 that a locale hook is provided with the layout handle.
  2809.                 The array is terminated by -1.
  2810.  
  2811.             LAPU_TabKey (BOOL) - Connect this object to the tabulator
  2812.                 key. Press [Tab] to cycle to the next entry, [Shift][Tab]
  2813.                 to cycle to the previous entry.
  2814.  
  2815.                     NOTE: there can be only one single button per
  2816.                         window to use this feature.
  2817.  
  2818.                 Default: FALSE
  2819.  
  2820.             LAPU_AutoPageID (LONG) - ID of paged GROUP_KIND object
  2821.                 which will be set to the gadget's current setting.
  2822.                 If this tag is set, you will hear no events from this
  2823.                 object any more.
  2824.  
  2825.                     NOTE: Listen to IDCMP_CLOSEWINDOW events
  2826.                         which may be generated if the layout
  2827.                         engine runs out of memory when rebuilding
  2828.                         the user interface.
  2829.  
  2830.             LAPU_CentreActive (BOOL) - If TRUE, the popup menu will
  2831.                 appear with the currently active entry centred below
  2832.                 the mouse pointer. (V31)
  2833.  
  2834.             LAPU_Labels (STRPTR *) - Pointer to NULL-terminated array
  2835.                 of strings that are the choices offered.
  2836.  
  2837.  
  2838.         SCROLLER_KIND:
  2839.  
  2840.             LASC_Thin (BOOL) - Make the scroller a bit thinner
  2841.                 than usual.
  2842.                 Default: FALSE
  2843.  
  2844.             GA_RelVerify (BOOL) - Hear every IDCMP_GADGETUP
  2845.                 event from scroller.
  2846.                 Default: TRUE
  2847.  
  2848.                         NOTE: This is different from what
  2849.                          gadtools.library uses.
  2850.  
  2851.             GA_Immediate (BOOL) - Hear every IDCMP_GADGETDOWN
  2852.                 event from scroller
  2853.                 Default: TRUE
  2854.  
  2855.                         NOTE: This is different from what
  2856.                          gadtools.library uses.
  2857.  
  2858.  
  2859.         SLIDER_KIND:
  2860.  
  2861.             LASL_FullCheck: TRUE will cause the code to rattle
  2862.                 through all possible slider settings, starting
  2863.                 from the minimum value, ending at the maximum value.
  2864.                 While this may be a good idea for a display
  2865.                 function to map slider levels to text strings
  2866.                 of varying length it might be a problem when
  2867.                 it comes to display a range of numbers from
  2868.                 1 to 40,000: the code will loop through
  2869.                 40,000 iterations trying to find the longest
  2870.                 string.
  2871.  
  2872.                 FALSE will cause the code to calculate the
  2873.                 longest level string based only on the
  2874.                 minimum and the maximum value to check.
  2875.                 While this is certainly a good a idea when
  2876.                 it comes to display a range of numbers from
  2877.                 1 to 40,000 as only two values will be
  2878.                 checked the code may fail to produce
  2879.                 accurate results for sliders using display
  2880.                 functions mapping slider levels to strings.
  2881.  
  2882.                 Default: TRUE
  2883.  
  2884.  
  2885.         STRING_KIND:
  2886.  
  2887.             LAST_LastGadget (BOOL) - Pressing return with this
  2888.                 gadget active will stop activating the next
  2889.                 following string gadget type if TRUE is passed.
  2890.                 Default: FALSE
  2891.  
  2892.             LAST_Link (LONG) - Gadget ID of the listview to attach
  2893.                 this string gadget to.
  2894.  
  2895.                     NOTE: you need to add the string gadget before
  2896.                         you add the listview to refer to it or the
  2897.                         layout routine will get confused.
  2898.  
  2899.             LAST_Picker (BOOL) - Attach a `select' button to the
  2900.                 right hand side of the string gadget.
  2901.                 Default: FALSE
  2902.  
  2903.             LAST_HistoryLines (LONG) - Number of lines to keep as
  2904.                 a backlog.
  2905.                 Default: 0
  2906.  
  2907.             LAST_HistoryHook (struct Hook *) - Hook code to call
  2908.                 when entering a line into the backlog. See gtlayout.h
  2909.                 for more information.
  2910.                 Default: NULL
  2911.  
  2912.             LAST_Activate (BOOL) - When the window opens, make this
  2913.                 gadget the active one. (V21)
  2914.  
  2915.                     NOTE: There can be only one gadget of this type
  2916.                         per window.
  2917.  
  2918.                 Default: FALSE
  2919.  
  2920.  
  2921.         TAB_KIND:
  2922.  
  2923.             (This features requires gtlayout.library v24 or higher)
  2924.  
  2925.             LATB_FirstLabel (LONG) - Locale string ID of the first
  2926.                 text to use as a label. Works in conjunction
  2927.                 with LATB_LastLabel.
  2928.  
  2929.             LATB_LastLabel (LONG) - Locale string ID of the last
  2930.                 text to use as a label. Works in conjunction
  2931.                 with LATB_FirstLabel. When building the interface the
  2932.                 code will loop from FirstLabel..LastLabel, look
  2933.                 up the corresponding locale strings and use the
  2934.                 data to make up the label text.
  2935.  
  2936.             LATB_LabelTable (LONG *) - Pointer to an array of IDs
  2937.                 to use for building the cycle labels. This requires
  2938.                 that a locale hook is provided with the layout handle.
  2939.                 The array is terminated by -1.
  2940.  
  2941.             LATB_TabKey (BOOL) - Connect this object to the tabulator
  2942.                 key. Press [Tab] to cycle to the next entry, [Shift][Tab]
  2943.                 to cycle to the previous entry.
  2944.  
  2945.                     NOTE: there can be only one single button per
  2946.                         window to use this feature.
  2947.  
  2948.                 Default: FALSE
  2949.  
  2950.             LATB_AutoPageID (LONG) - ID of paged GROUP_KIND object
  2951.                 which will be set to the gadget's current setting.
  2952.                 If this tag is set, you will hear no events from this
  2953.                 object any more.
  2954.  
  2955.                     NOTE: Listen to IDCMP_CLOSEWINDOW events
  2956.                         which may be generated if the layout
  2957.                         engine runs out of memory when rebuilding
  2958.                         the user interface.
  2959.  
  2960.             LATB_FullSize (BOOL) - By default a TAB_KIND object
  2961.                 covers the entire width of the group it sits in.
  2962.                 With LATB_FullSize set to true it will cover the
  2963.                 width of the entire Window.
  2964.  
  2965.                 Default: FALSE
  2966.  
  2967.             LATB_Labels (STRPTR *) - Pointer to NULL-terminated array
  2968.                 of strings that are the choices offered.
  2969.  
  2970.  
  2971.         TAPEDECK_KIND:
  2972.  
  2973.             LATD_ButtonType (LONG) - Select the image to display
  2974.                 in the button, must be one of the following:
  2975.  
  2976.                     TDBT_BACKWARD
  2977.                         "<<" Symbol
  2978.  
  2979.                     TDBT_FORWARD
  2980.                         ">>" Symbol
  2981.  
  2982.                     TDBT_PREVIOUS
  2983.                         "|<" Symbol
  2984.  
  2985.                     TDBT_NEXT
  2986.                         ">|" Symbol
  2987.  
  2988.                     TDBT_STOP
  2989.                         Stop symbol (filled square)
  2990.  
  2991.                     TDBT_PAUSE
  2992.                         "||" pause symbol (broken square)
  2993.  
  2994.                     TDBT_RECORD
  2995.                         Record symbol (filled circle)
  2996.  
  2997.                     TDBT_REWIND
  2998.                         "<" symbol
  2999.  
  3000.                     TDBT_EJECT
  3001.                         Eject symbol (broken upward pointing arrow)
  3002.  
  3003.                     TDBT_PLAY
  3004.                         ">" symbol
  3005.  
  3006.             LATD_Toggle (BOOL) - Make this object a toggle-select
  3007.                 button.
  3008.                 Default: FALSE
  3009.  
  3010.             LATD_Pressed (BOOL) - Make this button appear to be
  3011.                 pressed.
  3012.  
  3013.                     NOTE: requires "LATD_Toggle,TRUE" attribute.
  3014.  
  3015.                 Default: FALSE
  3016.  
  3017.             LATD_Smaller (BOOL) - Make this button a bit smaller
  3018.                 than usual.
  3019.                 Default: FALSE
  3020.  
  3021.             LATD_Tick (BOOL) - Hear IDCMP_GADGETUP events while the
  3022.                 buttons is being pressed; the IntuiMessage->Code entry
  3023.                 will be 0 while the button is being pressed, and
  3024.                 will be 1 as soon as the button is released. (V12)
  3025.  
  3026.                 Default: FALSE
  3027.  
  3028.  
  3029.         TEXT_KIND:
  3030.  
  3031.             LATX_Picker (BOOL) - Attach a `select' button to the
  3032.                 right hand side of the text display.
  3033.                 Default: FALSE
  3034.  
  3035.             LATX_LockSize (BOOL) - After doing the initial layout
  3036.                 for this object, do not adapt its size again during
  3037.                 subsequent layouts. This is particularly useful if
  3038.                 you have a TEXT_KIND object in a paged group
  3039.                 and update its contents later. You need
  3040.                 to specify an object width using LA_Chars, otherwise
  3041.                 the layout engine may make it not wide enough to
  3042.                 display any text. (V15)
  3043.  
  3044.  
  3045.         VERTICAL_KIND (group to align objects vertically):
  3046.         HORIZONTAL_KIND (group to align objects horizontally):
  3047.  
  3048.             LAGR_Spread (BOOL) - Place all objects in this
  3049.                 group with roughly the same amount of space
  3050.                 between them.
  3051.                 Default: FALSE
  3052.  
  3053.             LAGR_SameSize (BOOL) - Make all objects in this
  3054.                 group the same size (for vertical groups:
  3055.                 the same height, for horizontal groups:
  3056.                 the same width).
  3057.                 Default: FALSE
  3058.  
  3059.             LAGR_LastAttributes (BOOL) - Try to copy the
  3060.                 size of the previous group for this new
  3061.                 group. May not work if this group turns
  3062.                 out to be larger than the previous group.
  3063.                 Default: FALSE
  3064.  
  3065.             LAGR_ActivePage (LONG) - Organize all child
  3066.                 groups as pages which can be flipped through
  3067.                 using LT_SetAttributes(). You need to
  3068.                 specify the number of the first page to
  3069.                 display, starting from 0.
  3070.  
  3071.                     NOTE: Specifying this tag actually enables
  3072.                         the paging feature. If you omit this
  3073.                         tag calls to flip to a specific
  3074.                         page will fail.
  3075.  
  3076.                 Default: No paging
  3077.  
  3078.             LAGR_Frame (BOOL) - Draw a recessed frame around
  3079.                 this group, even if there is no group label. (V7)
  3080.  
  3081.             LAGR_IndentX (BOOL) - Add extra horizontal indentation
  3082.                 for this group. (V10)
  3083.  
  3084.             LAGR_IndentY (BOOL) - Add extra vertical indentation
  3085.                 for this group. (V10)
  3086.  
  3087.             LAGR_NoIndent (BOOL) - Inhibit automatic size adjustion
  3088.                 and centring of this group if it is smaller than
  3089.                 the neighbouring groups. (V21)
  3090.  
  3091.             LAGR_SameWidth (WORD) - During the final layout pass,
  3092.                 make this group the same width as the group which
  3093.                 uses the given ID. Not implemented yet. (V25)
  3094.  
  3095.             LAGR_SameHeight (WORD) - During the final layout pass,
  3096.                 make this group the same height as the group which
  3097.                 uses the given ID. Not implemented yet. (V25)
  3098.  
  3099.             LAGR_FrameGroup (UWORD) - Surround this group with a
  3100.                 frame. Must be one of FRAMETYPE_Label or FRAMETYPE_Tab.
  3101.                 FRAMETYPE_Label works like "LAGR_Frame,TRUE," while
  3102.                 FRAMETYPE_Tab is for use with a TAB_KIND object you
  3103.                 must put directly on top of this group or the group
  3104.                 will look a little silly. (V38)
  3105.  
  3106.                 Default: FRAMETYPE_None
  3107.  
  3108.  
  3109.         XBAR_KIND (horizontal separator bar):
  3110.  
  3111.             LAXB_FullSize (BOOL) - Make this separator bar span
  3112.                 the entire window width.
  3113.  
  3114.  
  3115.         YBAR_KIND (vertical separator bar):
  3116.  
  3117.             No tags are defined for this type of object.
  3118.  
  3119.  
  3120.    RESULT
  3121.     none
  3122.  
  3123.    BUGS
  3124.     Up to v25 the SCROLLER_KIND object did not support GA_Immediate
  3125.     or GA_RelVerify. The space for the variables was there, but the
  3126.     code was missing.
  3127.  
  3128.     POPUP_KIND objects don't work well in simple refresh windows,
  3129.     as refresh events can get lost. Use a smart refresh window
  3130.     instead or call gadtools.library/LT_CatchUpRefresh() regularly.
  3131.  
  3132.    SEE ALSO
  3133.     gadtools.library/CreateGadgetA
  3134.  
  3135. gtlayout.library/LT_NewLevelWidth           gtlayout.library/LT_NewLevelWidth
  3136.  
  3137.    NAME
  3138.     LT_NewLevelWidth -- Determine the maximum width of a SLIDER_KIND
  3139.                         level string. (V14)
  3140.  
  3141.    SYNOPSIS
  3142.     Index = LT_LevelWidth(Handle,FormatString,DispFunc,Min,Max,MaxWidth,
  3143.       D0                    A0        A1         A2     D0  D1    A3
  3144.  
  3145.                               MaxLen,FullCheck);
  3146.                                 D3      D2
  3147.  
  3148.     LONG LT_LevelWidth(LayoutHandle *,STRPTR,
  3149.                        LONG (*)(struct Gadget *,WORD),LONG,LONG,LONG *,
  3150.                        LONG *,BOOL);
  3151.  
  3152.    FUNCTION
  3153.     In order to make room for the level text displayed by a
  3154.     SLIDER_KIND object one needs to know how much space the
  3155.     longest level string will occupy. Otherwise, the level
  3156.     text may overwrite the gadget label text or the slider
  3157.     container. This routine will rattle through all possible
  3158.     slider settings (as given via the Min and the Max
  3159.     level values) and determine the longest label string
  3160.     according to the font used.
  3161.  
  3162.    INPUTS
  3163.     Handle - Pointer to a LayoutHandle structure, as returned by
  3164.         a call to LT_CreateHandleTags().
  3165.  
  3166.     FormatString - The sprintf() style formatting string to be used
  3167.         to format the slider level settings into text.
  3168.         This is the same string you would pass in via
  3169.         the GTSL_LevelFormat tag when creating the
  3170.         slider object.
  3171.         Default: "%lD" for systems which have locale.library
  3172.             installed, "%ld" otherwise.
  3173.  
  3174.     DispFunc - A pointer to the function to filter the slider level
  3175.         values. The result of this function will then be
  3176.         used to format a string into the slider level text.
  3177.         This is the same parameter you would pass in via
  3178.         the GTSL_DispFunc tag when creating the slider
  3179.         object.
  3180.  
  3181.         NOTE: the routine will be called with a NULL Gadget
  3182.             parameter, make sure your code will handle
  3183.             this nicely.
  3184.  
  3185.         Default: no display function
  3186.  
  3187.     Min - The smallest value the slider can be set to. This is
  3188.         same value you would pass in via GTSL_Min when creating
  3189.         the slider object.
  3190.  
  3191.     Max - The largest value the slider can be set to. This is
  3192.         same value you would pass in via GTSL_Max when creating
  3193.         the slider object.
  3194.  
  3195.     MaxWidth - Pointer to a place to store the width of the
  3196.         longest level string in pixels. If you pass
  3197.         in NULL instead of the address of a variable
  3198.         no harm will be done.
  3199.  
  3200.     MaxLen - Pointer to a place to store the length of the
  3201.         longest level string in characters. If you pass
  3202.         in NULL instead of the address of a variable
  3203.         no harm will be done.
  3204.  
  3205.     FullCheck - TRUE will cause the code to rattle through all
  3206.         possible slider settings, starting from the
  3207.         minimum value, ending at the maximum value.
  3208.         While this may be a good idea for a display
  3209.         function to map slider levels to text strings
  3210.         of varying length it might be a problem when
  3211.         it comes to display a range of numbers from
  3212.         1 to 40,000: the code will loop through
  3213.         40,000 iterations trying to find the longest
  3214.         string.
  3215.  
  3216.         FALSE will cause the code to calculate the
  3217.         longest level string based only on the
  3218.         minimum and the maximum value to check.
  3219.         While this is certainly a good a idea when
  3220.         it comes to display a range of numbers from
  3221.         1 to 40,000 as only two values will be
  3222.         checked the code may fail to produce
  3223.         accurate results for sliders using display
  3224.         functions mapping slider levels to strings.
  3225.  
  3226.    RESULT
  3227.     Index - The slider level which gives the longest
  3228.         level string.
  3229.  
  3230.    NOTES
  3231.     This function does exactly what gtlayout.library/LT_LevelWidth
  3232.     does, but uses a slightly different register ordering. Namely,
  3233.     the MaxLen pointer is passed in D3 instead of A5.
  3234.  
  3235.    SEE ALSO
  3236.     gtlayout.library/LT_LevelWidth
  3237.  
  3238. gtlayout.library/LT_NewMenuTagList         gtlayout.library/LT_NewMenuTagList
  3239.  
  3240.    NAME
  3241.     LT_NewMenuTagList -- Allocate and layout menu items (V11)
  3242.  
  3243.    SYNOPSIS
  3244.     Menu = LT_NewMenuTagList(Tags)
  3245.      D0                       A0
  3246.  
  3247.     struct Menu *LT_NewMenuTagList(struct TagItem *);
  3248.  
  3249.     struct Menu *LT_NewMenuTags(...);
  3250.  
  3251.    FUNCTION
  3252.     Allocates Menus and MenuItems similar to LT_LayoutMenus().
  3253.  
  3254.     As of v18 this routine will validate menu mutual exclusion
  3255.     information.
  3256.  
  3257.    INPUTS
  3258.     Tags - Pointer to a list of tagitem values, as found
  3259.         in gtlayout.h
  3260.  
  3261.  
  3262.     Valid tags include:
  3263.  
  3264.     LAMN_Screen (struct Screen *) - Pointer to the Screen
  3265.         the menu is to appear upon. This tag is mandatory,
  3266.         unless the LAMN_LayoutHandle tag is used.
  3267.  
  3268.     LAMN_TextAttr (struct TextAttr *) - Pointer to the
  3269.         TextAttr to use for the menu layout. If this tag
  3270.         is omitted the Screen->Font will be used.
  3271.  
  3272.     LAMN_Error (LONG *) - Pointer to variable to receive
  3273.         an error in case of failure.
  3274.  
  3275.     LAMN_AmigaGlyph (struct Image *) - Pointer to Image to
  3276.         use as the Amiga glyph in menus. Will be ignored if
  3277.         NULL.
  3278.  
  3279.         NOTE: Ignored by intuition.library v37 and below.
  3280.  
  3281.     LAMN_CheckmarkGlyph (struct Image *) - Pointer to Image to
  3282.         use as the checkmark glyph in menus. Will be ignored
  3283.         if NULL.
  3284.  
  3285.     LAMN_LayoutHandle (LayoutHandle *) - Pointer to a valid
  3286.         LayoutHandle as created by LT_CreateHandle. This tag
  3287.         provides all the information the single tags
  3288.         LAMN_Screen..LAMN_CheckmarkGlyph would otherwise
  3289.         need to provide.
  3290.  
  3291.     LAMN_TitleText (STRPTR) - Name of new menu to create.
  3292.         You may precede the name with the keyboard shortcut
  3293.         to assign to this menu item as follows:
  3294.  
  3295.            A\0Save as...
  3296.  
  3297.         This will create a menu item using the shortcut "A"
  3298.         and the title "Save as...".
  3299.  
  3300.     LAMN_TitleID (LONG) - Locale ID corresponding to the
  3301.         name of the new menu to create.
  3302.         You may precede the name with the keyboard shortcut
  3303.         to assign to this menu item as follows:
  3304.  
  3305.            A\0Save as...
  3306.  
  3307.         This will create a menu item using the shortcut "A"
  3308.         and the title "Save as...".
  3309.  
  3310.     LAMN_ItemText (STRPTR) - Name of new menu item to create.
  3311.         You may precede the name with the keyboard shortcut
  3312.         to assign to this menu item as follows:
  3313.  
  3314.            A\0Save as...
  3315.  
  3316.         This will create a menu item using the shortcut "A"
  3317.         and the title "Save as...".
  3318.  
  3319.     LAMN_ItemID (LONG) - Locale ID corresponding to the
  3320.         name of the new menu item to create.
  3321.         You may precede the name with the keyboard shortcut
  3322.         to assign to this menu item as follows:
  3323.  
  3324.            A\0Save as...
  3325.  
  3326.         This will create a menu item using the shortcut "A"
  3327.         and the title "Save as...".
  3328.  
  3329.     LAMN_SubText (STRPTR) - Name of new submenu item to create.
  3330.         You may precede the name with the keyboard shortcut
  3331.         to assign to this menu item as follows:
  3332.  
  3333.            A\0Save as...
  3334.  
  3335.         This will create a menu item using the shortcut "A"
  3336.         and the title "Save as...".
  3337.  
  3338.     LAMN_SubID (LONG) - Locale ID corresponding to the
  3339.         name of the new submenu item to create.
  3340.         You may precede the name with the keyboard shortcut
  3341.         to assign to this menu item as follows:
  3342.  
  3343.            A\0Save as...
  3344.  
  3345.         This will create a menu item using the shortcut "A"
  3346.         and the title "Save as...".
  3347.  
  3348.     LAMN_KeyText (STRPTR) - Pointer to the string whose first
  3349.         character will be used as the keyboard shortcut for
  3350.         this menu/submenu item.
  3351.  
  3352.     LAMN_KeyID (LONG) - Locale ID corresponding to the string whose
  3353.         first character will be used as the keyboard shortcut for
  3354.         this menu/submenu item.
  3355.  
  3356.     LAMN_CommandText (STRPTR) - Pointer to the string which
  3357.         will be used as the keyboard shortcut for this
  3358.         menu/submenu item.
  3359.  
  3360.     LAMN_CommandID (LONG) - Locale ID corresponding to the string
  3361.         which will be used as the keyboard shortcut for
  3362.         this menu/submenu item.
  3363.  
  3364.     LAMN_MutualExclude (ULONG) - Mutual exclusion information for
  3365.         this menu/submenu item.
  3366.  
  3367.     LAMN_UserData (APTR) - User data information for this
  3368.         menu/menu item/submenu item.
  3369.  
  3370.     LAMN_Disabled (BOOL) - Controls whether this
  3371.         menu/menu item/submenu item should be disabled.
  3372.  
  3373.     LAMN_CheckIt (BOOL) - Controls whether this menu/submenu item
  3374.         should be prepared to hold a checkmark.
  3375.  
  3376.             NOTE: This does not set the checkmark, use LAMN_Checked
  3377.                 for this purpose.
  3378.  
  3379.     LAMN_Checked (BOOL) - Controls whether this menu/submenu item
  3380.         should be marked with a checkmark. This tag implies
  3381.         "LAMN_CheckIt,TRUE".
  3382.  
  3383.     LAMN_Toggle (BOOL) - Controls whether this menu/submenu item
  3384.         should be prepared to hold a checkmark the user is to
  3385.         toggle on demand. This tag implies "LAMN_CheckIt,TRUE".
  3386.  
  3387.             NOTE: this does not set the checkmark, use LAMN_Checked
  3388.                 for this purpose.
  3389.  
  3390.     LAMN_Code (UWORD) - Raw key code to associate with this
  3391.         menu/submenu item. To find out if a rawkey event
  3392.         corresponds to this menu item use LT_FindMenuCommand.
  3393.  
  3394.     LAMN_Qualifier (ULONG) - Key qualifier to associate
  3395.         with this menu/submenu item.
  3396.  
  3397.             NOTE: the comparison does not distinguish between
  3398.                 the left and right shift/caps/alt qualifier keys.
  3399.  
  3400.     LAMN_ID (ULONG) - Unique ID to associate with this
  3401.         menu/menu item/submenu item. You can use this
  3402.         later to look up data using LT_GetMenuItem, etc.
  3403.  
  3404.     LAMN_ExtraSpace (UWORD) - Number of pixels to put between
  3405.         neighbouring menu titles. (V18)
  3406.         Default: 0 pixels.
  3407.  
  3408.    RESULT
  3409.     Menu - Pointer to Menu structure, ready to pass to
  3410.            SetMenuStrip(), NULL on failure.
  3411.  
  3412.    EXAMPLE
  3413.     The following tagitem list:
  3414.  
  3415.         LAMN_TitleText,     "Project"
  3416.          LAMN_ItemText,     "New",
  3417.           LAMN_KeyText,     "N",
  3418.          LAMN_ItemText,     "Open...",
  3419.           LAMN_KeyText,     "O",
  3420.          LAMN_ItemText,     NM_BARLABEL,
  3421.          LAMN_ItemText,     "Save",
  3422.           LAMN_KeyText,     "S",
  3423.          LAMN_ItemText,     "A\0Save As...",
  3424.          LAMN_ItemText,     NM_BARLABEL,
  3425.          LAMN_ItemText,     "Print...",
  3426.           LAMN_KeyText,     "P",
  3427.          LAMN_ItemText,     NM_BARLABEL,
  3428.          LAMN_ItemText,     "Help...",
  3429.           LAMN_CommandText, "[Help]",
  3430.          LAMN_ItemText,     NM_BARLABEL,
  3431.          LAMN_ItemText,     "Quit...",
  3432.           LAMN_KeyText,     "Q",
  3433.         TAG_DONE
  3434.  
  3435.     Will create the following menu:
  3436.  
  3437.     +-------+
  3438.     |Project|
  3439.     +-------+------+
  3440.     |New         aN|
  3441.     |Open...     aO|
  3442.     |~~~~~~~~~~~~~~|
  3443.     |Save        aS|
  3444.     |Save As...  aA|
  3445.     |~~~~~~~~~~~~~~|
  3446.     |Print...    aP|
  3447.     |~~~~~~~~~~~~~~|
  3448.     |Help... [Help]|
  3449.     |~~~~~~~~~~~~~~|
  3450.     |Quit...     aQ|
  3451.     +--------------+
  3452.  
  3453.    NOTES
  3454.     You may freely add, remove, spindle & mutilate the contents of the
  3455.     menu strip created, just don't trash or disconnect the base menu
  3456.     entry this routine creates as all menu memory tracking data is
  3457.     connected to it.
  3458.  
  3459.    SEE ALSO
  3460.     gtlayout.library/LT_DisposeMenu
  3461.     gtlayout.library/LT_FindCommandItem
  3462.     gtlayout.library/LT_GetMenuItem
  3463.     gtlayout.library/LT_LayoutMenuA
  3464.     gtlayout.library/LT_MenuControlTagList
  3465.     gtlayout.library/LT_NewMenuTemplate
  3466.     intuition.library/SetMenuStrip
  3467.  
  3468. gtlayout.library/LT_NewMenuTemplate       gtlayout.library/LT_NewMenuTemplate
  3469.  
  3470.    NAME
  3471.     LT_NewMenuTemplate -- Allocate and layout menu items (V11)
  3472.  
  3473.    SYNOPSIS
  3474.     Menu = LT_NewMenuTemplate(Screen,TextAttr,AmigaGlyph,CheckmarkGlyph,
  3475.      D0                         A0      A1        A2           A3
  3476.  
  3477.                               Error,MenuTemplate);
  3478.                                 D0      D1
  3479.  
  3480.     struct Menu *LT_NewMenuTemplate(struct Screen *,struct TextAttr *,
  3481.                                     struct Image *,struct Image *,
  3482.                                     LONG *,struct NewMenu *);
  3483.  
  3484.    FUNCTION
  3485.     Allocates Menus and MenuItems similar to LT_LayoutMenus().
  3486.  
  3487.     As of v18 this routine will validate menu mutual exclusion
  3488.     information.
  3489.  
  3490.    INPUTS
  3491.     Screen - Pointer to the screen the menu will appear on. This
  3492.         parameter is required and must not be omitted.
  3493.  
  3494.     TextAttr - Pointer to the TextAttr that should be used to
  3495.         layout the menus. If this parameter is omitted,
  3496.         Screen->Font will be used instead.
  3497.  
  3498.     AmigaGlyph - Pointer to the Image to use as the Amiga glyph.
  3499.         This parameter may be omitted.
  3500.  
  3501.             NOTE: Ignored by intuition.library v37 and below.
  3502.  
  3503.     CheckmarkGlyph - Pointer to the Image to use as the checkmark
  3504.         glyph. This parameter may be omitted.
  3505.  
  3506.     Error - Pointer to receive error code in case the menu
  3507.         creation or layout process fails. This parameter
  3508.         may be omitted.
  3509.  
  3510.     MenuTemplate - Pointer to a series of NewMenu structures,
  3511.         just as you would pass to
  3512.         gtlayout.library/LT_LayoutMenuA.
  3513.  
  3514.    RESULT
  3515.     Menu - Pointer to Menu structure, ready to pass to
  3516.         SetMenuStrip(), NULL on failure.
  3517.  
  3518.    NOTES
  3519.     The menu created by this function cannot be used with the
  3520.     routines LT_MenuControlTagList, LT_FindMenuCommand and
  3521.     LT_GetMenuItem.
  3522.  
  3523.     You may freely add, remove, spindle & mutilate the contents of the
  3524.     menu strip created, just don't trash or disconnect the base menu
  3525.     entry this routine creates as all menu memory tracking data is
  3526.     connected with it.
  3527.  
  3528.    SEE ALSO
  3529.     gtlayout.library/LT_DisposeMenu
  3530.     gtlayout.library/LT_LayoutMenuA
  3531.     gtlayout.library/LT_NewMenuTagList
  3532.     intuition.library/SetMenuStrip
  3533.  
  3534. gtlayout.library/LT_PressButton               gtlayout.library/LT_PressButton
  3535.  
  3536.    NAME
  3537.     LT_PressButton -- Highlight a button so it looks as if the user
  3538.                       has selected it.
  3539.  
  3540.    SYNOPSIS
  3541.     Success = LT_PressButton(Handle,ID);
  3542.        D0                       A0  D0
  3543.  
  3544.     BOOL LT_PressButton(LayoutHandle *,LONG);
  3545.  
  3546.         NOTE: The return value did not exist until V39!
  3547.  
  3548.    FUNCTION
  3549.     You can provide visual feedback for BUTTON_KIND objects by calling
  3550.     this routine. They will briefly appear to be selected and then
  3551.     fall back to their original states.
  3552.  
  3553.     As of V39 and beyond this function will indicate whether the button
  3554.     could be highlighted or not.
  3555.  
  3556.    INPUTS
  3557.     Handle - Pointer to LayoutHandle structure
  3558.  
  3559.     ID - ID of button object to highlight
  3560.  
  3561.    RESULT
  3562.     Success (V39) - TRUE if button could be highlighted, FALSE otherwise.
  3563.  
  3564. gtlayout.library/LT_RebuildTagList         gtlayout.library/LT_RebuildTagList
  3565.  
  3566.    NAME
  3567.     LT_RebuildTagList -- Rebuild the user interface after modifying it.
  3568.  
  3569.    SYNOPSIS
  3570.     Success = LT_RebuildTagList(Handle,Clear,TagList);
  3571.        D0                         A0    D0     A1
  3572.  
  3573.     BOOL LT_RebuildTagList(LayoutHandle *,BOOL,struct TagItem *);
  3574.  
  3575.     Success = LT_RebuildTags(Handle,Clear,...);
  3576.  
  3577.     BOOL LT_RebuildTags(LayoutHandle *,BOOL,...);
  3578.  
  3579.    FUNCTION
  3580.     Certain aspects of the user interface can be changed at run time,
  3581.     such as button labels. This routine will let you rebuild the interface
  3582.     based upon the data supplied at creation time and your subsequent
  3583.     changes. Before you make any vital changes, it is recommended to
  3584.     lock the window using LT_LockWindow() in order to avoid clashes
  3585.     with the Intuition and GadTools subsystems.
  3586.  
  3587.    INPUTS
  3588.     Handle - Pointer to LayoutHandle structure.
  3589.  
  3590.     Clear - Pass in TRUE if you wish to have the window contents
  3591.         cleared before they are rebuild. This will introduce
  3592.         some visual hashing.
  3593.  
  3594.     TagList - Attributes controlling the layout process.
  3595.  
  3596.  
  3597.     Valid tags include:
  3598.  
  3599.     LAWN_Bounds (struct IBox *) - Boundaries in which the window
  3600.         should be centered.
  3601.  
  3602.     LAWN_ExtraWidth (LONG) - Extra space to add to the window
  3603.         width.
  3604.  
  3605.     LAWN_ExtraHeight (LONG) - Extra height to add to the window
  3606.         height.
  3607.  
  3608.    RESULT
  3609.     Success - TRUE indicates that the interface was rebuilt,
  3610.         FALSE indicates trouble; it is recommended to
  3611.         call LT_DeleteHandle() on your LayoutHandle as
  3612.         soon as possible as the previous operation may
  3613.         have left the user interface in an inoperable
  3614.         state.
  3615.  
  3616. gtlayout.library/LT_Refresh                       gtlayout.library/LT_Refresh
  3617.  
  3618.    NAME
  3619.     LT_Refresh -- Redraws the entire window contents.
  3620.  
  3621.    SYNOPSIS
  3622.     LT_Refresh(Handle)
  3623.                  A0
  3624.  
  3625.     VOID LT_Refresh(LayoutHandle *);
  3626.  
  3627.    FUNCTION
  3628.     Redraws the contents of the window, this includes both gadgets
  3629.     and imagery.
  3630.  
  3631.    INPUTS
  3632.     Handle - Pointer to a LayoutHandle structure.
  3633.  
  3634.    RESULT
  3635.     none
  3636.  
  3637.    SEE ALSO
  3638.        gadtools.library/GT_RefreshWindow
  3639.        intuition.library/RefreshGList
  3640.  
  3641. gtlayout.library/LT_ReplyIMsg                   gtlayout.library/LT_ReplyIMsg
  3642.  
  3643.    NAME
  3644.     LT_ReplyIMsg -- Dispose of an IntuiMessage received
  3645.  
  3646.    SYNOPSIS
  3647.     LT_ReplyIMsg(IntuiMessage);
  3648.                      A0
  3649.  
  3650.     VOID LT_ReplyIMsg(struct IntuiMessage *);
  3651.  
  3652.    FUNCTION
  3653.     This routine complements LT_GetIMsg().
  3654.  
  3655.    INPUTS
  3656.     IntuiMessage - Pointer to IntuiMessage structure,
  3657.         passing NULL is harmless.
  3658.  
  3659.    RESULT
  3660.     none
  3661.  
  3662.    NOTES
  3663.     Only pass IntuiMessages you received via LT_GetIMsg,
  3664.     or things will get tough.
  3665.  
  3666.    SEE ALSO
  3667.     gtlayout.library/LT_GetIMsg
  3668.  
  3669. gtlayout.library/LT_SetAttributesA         gtlayout.library/LT_SetAttributesA
  3670.  
  3671.    NAME
  3672.     LT_SetAttributesA -- Change object attributes
  3673.  
  3674.    SYNOPSIS
  3675.     LT_SetAttributesA(Handle,ID,Tags);
  3676.                         A0   D0  A1
  3677.  
  3678.     VOID LT_SetAttributes(LayoutHandle *,LONG,struct TagItem *);
  3679.  
  3680.     LT_SetAttributes(Handle,ID,...);
  3681.  
  3682.     VOID LT_SetAttributes(LayoutHandle *,LONG,...);
  3683.  
  3684.    FUNCTION
  3685.     This routine passes the tag item list it gets directly
  3686.     over to GT_SetGadgetAttrsA(), so any tag items valid for
  3687.     gadtools.library can be used here as well. Some filtering
  3688.     may be done in order to stop objects from getting redrawn
  3689.     if this is not absolutely necessary.
  3690.  
  3691.    INPUTS
  3692.     Handle - Pointer to LayoutHandle.
  3693.  
  3694.     ID - ID number of the object to change. This is the same value
  3695.         you passed via LA_ID to LT_New() when you created this object.
  3696.  
  3697.     Tags - Attributes controlling object states.
  3698.  
  3699.  
  3700.     All gadtools.library tags are allowed, but not all are supported.
  3701.     In addition to these tags a few additional tag values are
  3702.     supported:
  3703.  
  3704.     LAHN_AutoActivate (BOOL) - Set to TRUE if you want the interface
  3705.         to always keep a string gadget active if possible. Hitting
  3706.         the return key will then cause the next following string
  3707.         gadget to get activated, either cycling through all the
  3708.         string gadgets available or stopping at the next string
  3709.         gadget to have the LAST_LastGadget attribute set.
  3710.  
  3711.     LAHN_UserData (APTR) - Store user specific data in the
  3712.         LayoutHandle->UserData entry. (V9)
  3713.  
  3714.     LAHN_RawKeyFilter (BOOL) - Discard unprocessed IDCMP_RAWKEY
  3715.         events. (V13)
  3716.         Default: TRUE
  3717.  
  3718.     LAHN_LocaleHook (struct Hook *) - The hook to call when
  3719.         locale string IDs are to be mapped to strings. The
  3720.         hook function is called with the following parameters:
  3721.  
  3722.         String = HookFunc(struct Hook *Hook,struct LayoutHandle *Handle,
  3723.           D0                            A0                         A2
  3724.                           LONG ID)
  3725.                                A1
  3726.  
  3727.         The function is to look up the string associated with the ID
  3728.         passed in and return the string.
  3729.  
  3730.     LAHN_ExitFlush (BOOL) - When the LayoutHandle is finally disposed
  3731.         of with LT_DeleteHandle() all variables maintained by the
  3732.         input handling code will be flushed. For example, if you
  3733.         would use the LA_STRPTR tag for STRING_KIND objects the
  3734.         last string gadget contents would be copied into the buffer
  3735.         pointed to by LA_STRPTR. If you do not want to use this
  3736.         feature, disable it with "LAHN_ExitFlush,FALSE". (V9)
  3737.         Default: TRUE
  3738.  
  3739.     GAUGE_KIND:
  3740.  
  3741.         LAGA_Percent (LONG) - Percentage of the gauge to fill.
  3742.  
  3743.         LAGA_InfoText (STRPTR) - Text to be printed within the
  3744.             gauge display, such as a percentage number.
  3745.  
  3746.     BOX_KIND:
  3747.  
  3748.         LABX_Index (LONG) - The number of the line to change, this
  3749.             tag works in conjunction with the LABX_Text tag.
  3750.  
  3751.         LABX_Text (STRPTR) - The text to put into the line indicated
  3752.             by the LABX_Index tag.
  3753.             As of v26 the LABX_Index tag may be omitted, the library
  3754.             will then assume the line index will be 0.
  3755.  
  3756.         LABX_Lines (STRPTR *) - The text to set for the box contents,
  3757.             terminate the text array with NULL.
  3758.  
  3759.     HORIZONTAL_KIND:
  3760.     VERTICAL_KIND:
  3761.  
  3762.         LAGR_ActivePage (LONG) - Index number of page to display
  3763.             within the group.
  3764.  
  3765.                 NOTE: requires that this group was created
  3766.                     with the LAGR_ActivePage attribute set.
  3767.  
  3768.     INTEGER_KIND:
  3769.  
  3770.         LAIN_Min (LONG) - Minimum allowed value for this
  3771.             object.
  3772.  
  3773.         LAIN_Max (LONG) - Maximum allowed value for this
  3774.             object.
  3775.  
  3776.     LISTVIEW_KIND:
  3777.  
  3778.         LALV_Selected (LONG) - Combines GTLV_Selected and
  3779.             GTLV_Top (for Kickstart V37) or GTLV_MakeVisible
  3780.             (for Kickstart V39 and greater). This means, the
  3781.             list display will be changed in order to show
  3782.             the item to be selected. (V34)
  3783.  
  3784.     LEVEL_KIND:
  3785.  
  3786.         LAVL_NumTicks (WORD) - Number of tick marks to draw
  3787.            next to the slider body.
  3788.  
  3789.     PASSWORD_KIND:
  3790.  
  3791.         LAPW_String (STRPTR) - Secret text to use
  3792.  
  3793.     POPUP_KIND
  3794.  
  3795.         LAPU_Labels (STRPTR *) - To block access to the popup
  3796.             menu, for example before you free the current list
  3797.             of labels, you can pass ~0 as the list parameter. (V25)
  3798.  
  3799.     STRING_KIND:
  3800.  
  3801.         LAST_CursorPosition (LONG) - Repositions the cursor,
  3802.             pass -1 to move it to the end of the string. (V7)
  3803.  
  3804.     TAPEDECK_KIND:
  3805.  
  3806.         LATD_Pressed (BOOL) - TRUE to make this button shown
  3807.             as pressed, FALSE to show it in depressed state.
  3808.  
  3809.     BOOPSI_KIND:
  3810.  
  3811.         All tags are passed straight through to SetGadgetAttrs(..).
  3812.  
  3813.     All objects:
  3814.  
  3815.         LA_LabelText (STRPTR) - New gadget label text to use.
  3816.  
  3817.         LA_LabelID (LONG) - Locale text ID to use for this object.
  3818.  
  3819.    RESULT
  3820.     none
  3821.  
  3822.    SEE ALSO
  3823.     gadtools.library/GT_SetGadgetAttrsA()
  3824.     intuition.library/SetGadgetAttrsA
  3825.  
  3826. gtlayout.library/LT_ShowWindow                 gtlayout.library/LT_ShowWindow
  3827.  
  3828.    NAME
  3829.     LT_ShowWindow -- Make a window visible
  3830.  
  3831.    SYNOPSIS
  3832.     LT_ShowWindow(Handle,Activate);
  3833.                     A0      A1
  3834.  
  3835.     VOID LT_ShowWindow(LayoutHandle *,BOOL);
  3836.  
  3837.    FUNCTION
  3838.     The window attached to a LayoutHandle is made visible, this
  3839.     involves bringing it to the front, bringing the screen to
  3840.     the front the window resides on, unzooming the window and
  3841.     also moving the visible part of an autoscrolling screen.
  3842.  
  3843.    INPUTS
  3844.     Window - Pointer to Window structure.
  3845.  
  3846.     Activate - If TRUE the window will be activated as soon
  3847.         as it has been brought to the front.
  3848.  
  3849.    RESULT
  3850.     none
  3851.  
  3852.    NOTES
  3853.     The arguments are passed in A0 and A1, this is *not* a
  3854.     typo.
  3855.  
  3856.    BUGS
  3857.     In revisions earlier than v21 this routine consistently
  3858.     failed to reliably unzip a window in zoomed state. This
  3859.     could cause the calling application to wait for about
  3860.     five seconds before continuing execution.
  3861.  
  3862.    SEE ALSO
  3863.     intuition.library/MoveScreen
  3864.     intuition.library/ScreenPosition
  3865.     intuition.library/ZipWindow
  3866.  
  3867. gtlayout.library/LT_UnlockWindow             gtlayout.library/LT_UnlockWindow
  3868.  
  3869.    NAME
  3870.     LT_UnlockWindow -- The complement to LT_LockWindow().
  3871.  
  3872.    SYNOPSIS
  3873.     LT_UnlockWindow(Window);
  3874.                       A0
  3875.  
  3876.     VOID LT_UnlockWindow(struct Window *);
  3877.  
  3878.    FUNCTION
  3879.     This routine unlocks a window locked using LT_LockWindow, freeing
  3880.     allocated memory, restoring the window characteristics to their
  3881.     original values.
  3882.  
  3883.    INPUTS
  3884.     Window - Pointer to window structure; passing NULL is harmless.
  3885.  
  3886.    RESULT
  3887.     none
  3888.  
  3889.    SEE ALSO
  3890.     gtlayout.library/LT_LockWindow
  3891.  
  3892. gtlayout.library/LT_UpdateStrings           gtlayout.library/LT_UpdateStrings
  3893.  
  3894.    NAME
  3895.     LT_UpdateStrings -- Make sure all visible string buffer contents
  3896.                         get written into storage (v9).
  3897.  
  3898.    SYNOPSIS
  3899.     LT_UpdateStrings(LayoutHandle);
  3900.                             A0
  3901.  
  3902.     VOID LT_UpdateStrings(struct LayoutHandle *);
  3903.  
  3904.    FUNCTION
  3905.     The user can terminate input into a string gadget or an object
  3906.     derived from a string gadget by various means. They all have
  3907.     in common that the application receives no notification that
  3908.     the string gadget contents have changed. This is particularly
  3909.     nasty with objects which make use of LA_STRPTR or other
  3910.     tags. Using LT_UpdateStrings() you can force all visible string
  3911.     gadget objects to hand over their contents to the internal
  3912.     buffers. Do this before you eventually exit your input loop.
  3913.  
  3914.    INPUTS
  3915.     LayoutHandle - Pointer to LayoutHandle structure.
  3916.  
  3917.    RESULT
  3918.     none
  3919.  
  3920.